On: Writing system software: code comments

[vbezhenar]

Writing good comments is not necessarily easy task. When you're writing code, everything seems obvious. You can write obvious comments, but they won't help. I think that best comments would be written by someone who came later and had to understand the code from the scratch.

[crdoconnor → vbezhenar]

I do this:

#1 If anything in a pull request isn't blindingly obvious, ask a "why are we doing this here?" style question.

#2 Encourage all developers to do this on all pull requests.

#3 Get developers to answer those questions in the form of a pushed code comment rather than (or as well as) answering the comment. Make that an iron rule.

IMHO this gives the best comments. I'd usually discourage comments that don't come about like this.

[rocqua → vbezhenar]

Or even just by yourself a little after you've written the code. When you yourself are trying to figure out how it all fits together exactly.