Hacker News new | past | comments | ask | show | jobs | submit login

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.

Guidelines | FAQ | Lists | API | Security | Legal | Apply to YC | Contact