Hacker News new | past | comments | ask | show | jobs | submit login
Ask HN: Suggest code commenting guidelines?
4 points by andrelaszlo on May 29, 2013 | hide | past | favorite | 2 comments
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.

Of course, comments like this are silly:

  # adds increment to height
  height += inc
But I think we can do better than just not being silly.

Do you use, or have you seen, a good guideline or set of rules for how to write good comments?

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.

"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.

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