Page Comparison

...

Table of Contents

Motivation and strategy

Code Comments help yourself as much as your co-workers to remember the important bits: code you wrote 6 months ago might as well have been written by someone else — you’ll thank yourself for the comments you are leaving for your future self.
Corollary: write comments to help yourself (and your co-workers) remember the important bits.
Write as if the audience was yourself prior to you writing the code.
Comments make a code base more approachable for new engineers.
Especially package-level or top-of-file comments that explain how pieces fit together.

When there are questions during a code review, add comments to explain the outcome of the review:
if the reviewer had questions, the next reader will too.
If you had to think about If you had to think about the design of your code, explain your design in prose in a comment no later than when you submit the code for review.
Write as if the audience was yourself prior to you writing the code.
When exploring / analyzing existing code, if you notice that you need to think hard to understand it, then make a PR to add comments with your new understanding. Also fix typos and grammar mistakes that impair the reading, as you find them.
Do so even if it's not your own code.
When there are questions during a code review, add comments to explain the outcome of the review:
if the reviewer had questions, the next reader will too.

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.

...