Hacker News Reader

Comment by tlrobinson | Hacker News Reader

Even better than documented code is code that's so clear it doesn't need explanation, with occasional comments explaining the complicated bits.

The other case is API docs for libraries and frameworks meant for external consumption.

View on HN

I absolutely agree. I don't comment all that much, but comment where it's impossible to get clarity -- or comment at a higher level to explain the rationale for the code.

Commenting what code does -- is either 1) pointless or 2) indicative you should rewrite your explanation-requiring code in a more straightforward fashion.

I comment for one person and one person only: myself in 6 months or 2 years when I've forgotten everything about this code! Strangely enough, that kind of attitude results in comments that everyone finds useful.

I actually comment even simple code because comments show up a different color in my editors. Comments for me are often an additional mnemonic trigger rather than necessarily a store of detailed information. It's like indenting or bolding text. It helps with "chunking" while skimming code.

The trouble is that the very same visual cue makes it easy to filter out comments as background noise, so people fail to read them (or even see them) when updating the associated code. As a result, comments don't get maintained and become inaccurate over time. It takes only a small amount of such semantic decay before the comments are a net negative.

Programmers take code seriously. Most don't take comments seriously, even when they believe they ought to. You might say they're bad programmers, but I don't think it's that simple. I think the attention goes straight to code for a reason.

For this purpose, whitespace is a much better tool than blocks of lorem ipsum.

Braces (in relevant langauges, like C and Java) are even better, because they tighten scoping and avoid unintentional variable re-use.

An experienced engineer told me the purpose of documenting is not to tell what the new few lines do, it is to explain something that does not look right, or something to be careful with.

Reply on news.ycombinator.com