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 a

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.