re: Good comments explain WHY, not WHAT, and 3 more rules on writing good comments VIEW POST


I fully agree based on the context I assume you're talking about (professional), and I think I know where the impulse toward what-type comments stems from: school.

What-type comments make sense in a learning situation where the teacher or professor has to quickly traverse many students' code and understand their implementation. Also, early in their skill development, student coding styles and naming conventions vary wildly, comments allow the instructor to classify different sections of student code easily. I can imagine an instructor reading a comment and thinking, "Oh this is the function they use to re-order their heap", or something similar.

This leads to think that different comments/documentation are needed in different contexts. In a professional environment, with standardized documentation and naming conventions, "what" is usually covered elsewhere and unnecessary. But in educational contexts, where the user is the instructor, a different strategy is needed.

I think the problem you describe stems from the failure of students and sometimes managers and supervisors to fully context switch and adopt a the style you're writing about.

code of conduct - report abuse