3 ms·
Good code should have some comments. Not for the "what" but for the "why".
by codegeek 5y ago
Good code should have some comments. Not for the "what" but for the "why".
- eyelidlessness 5y agoThis 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.