Re:Writing system software: code comments
by vbezhenar on Sunday October 07, 2018 @06:40AM
(#18159901)
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.
[ Parent
| on HN ]
Re:Writing system software: code comments
by crdoconnor on Sunday October 07, 2018 @10:38AM
(#18160747)
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.