...
Write comments that read the code underneath “out loud”, for example:
“this line increments the variable x” for
x++.“now we iterate over all the strings” for
for i := range strs
When reviewing a PR, put too much emphasis on comment grammar.
Grammar remains prefixed by “nits:” in reviews.
Updating comments over time
When you discover something valuable that should be explained in a comment, but is not yet explained, consider adding/extending a comment with your new knowledge. The next reader will thank you.
If you find a mistake in a comment, it can be a good use of your time to fix it.
If a comment is factually incorrect, then you should consider it as an outright bug and either attempt to fix it immediately or file an issue.
If it contains a grammatical or spelling error that makes the reading particularly difficult, it would be valuable to the team and your future self to fix it too.
Beware of “cosmetic” improvements, e.g. changing one word for another, or fixing “simple” typos that don’t hurt reading. The time spent on creating a commit and a PR and getting it reviewed might not be worth the marginal value of the improvement, unless you can combine the improvement with a larger project.
Also consider the marginal impact of aesthetic changes on automation and the output of
git blame, as discussed here.
Examples
Top-level design comments
...