Re:Ask HN: What if code comments were not supported?
by eyelidlessness on Wednesday October 13, 2021 @08:40PM
(#28859277)
This is correct. But I think it confounds a lot of people because “comments” are often overloaded. E.g. comments used for tooling and API-facing documentation are not always distinguishable from comments intended for maintainers.
The former is supposed to answer “what”. You’re describing the characteristics of a part of the elephant, from the perspective of knowing the whole elephant.
In the latter, “why” is what determines whether a code comment is valuable (or if the code under comment is itself questionable). If your comment needs to explain to maintainers (including future-you) what the code does, it’s a huge red flag. The most reasonable exceptions to that are: important optimizations that obscure understanding the code by reading it; you have to interact with APIs out of your control that force you to write hard to understand code.
The former is supposed to answer “what”. You’re describing the characteristics of a part of the elephant, from the perspective of knowing the whole elephant.
In the latter, “why” is what determines whether a code comment is valuable (or if the code under comment is itself questionable). If your comment needs to explain to maintainers (including future-you) what the code does, it’s a huge red flag. The most reasonable exceptions to that are: important optimizations that obscure understanding the code by reading it; you have to interact with APIs out of your control that force you to write hard to understand code.