

Ask HN: Suggest code commenting guidelines? - andrelaszlo

If you google for code comment guidelines, you find a lot of rules about indentation and such, but much less information about the actual content of the comments.<p>Of course, comments like this are silly:<p><pre><code>  # adds increment to height
  height += inc
</code></pre>
But I think we can do better than just not being silly.<p>Do you use, or have you seen, a good guideline or set of rules for how to write good comments?
======
frou_dh
Enabling skim-reading seems a decent goal.

As in, write comments such that someone can quickly get a high-to-mid-level
understanding of what's happening in a given unit of code[0], with the
unabridged version being the code itself.

0: The smallest unit worth commenting being a logical group of lines within a
function, usually padded with newlines above and below.

------
andrelaszlo
"Function comments should describe the intent of a function, not the
implementation" found at <http://stackoverflow.com/a/2357285/98057> is a good
start, I guess.

