5 ms·
Ask HN: Suggest code commenting guidelines?
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?
- andrelaszlo 13y ago"Function comments should describe the intent of a function, not the implementation" found at http://stackoverflow.com/a/2357285/98057 http://stackoverflow.com/a/2357285/98057 is a good start, I guess.
- frou_dh 13y agoEnabling 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.
- deleted 13y ago[deleted]