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.explain how pieces fit together.

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.

...