Know your audience; generally experienced programmers. The important thing
about comments is that you don’t write them for yourself. You write them for
future maintainers (possibly your own future self). They are not intended for
programming novices (except for teaching demos, where they are very useful).
All comments should be spell-checked and clear in what they convey to the
reader. In general, comments should appear near the code they describe, such
as at the end of a line of code or in a separate line just above the code.

[A goal of writing good documentation is to anticipate the readers’
perspectives.]

There are four different types of comments: what, how, why, and required. Let's
start with the "what comments".

"What comments" refer to the actual steps taken.
Use what comments to describe what a chunk (also called a code fragment or
snippet) of code is doing. Simple, clear code needs fewer (or no) what
comments. If during a code review you ask the author what a chunk of code is
doing, it either means that their code is unclear and/or the what comments are
deficient. Complex formulas, algorithms, regular expressions, and formats (file
formats, date/time formats, and others), all need what comments.

When brain-storming using pseudocode, the steps you discover can become what
comments which are place-holders for code you intend to add, and you fill in
the code later. All incomplete code should have these TODO comments, and often
you put that word in the comment to find such spots easily. Once you added the
code you remove the comment. (It is redundant “noise” at this point.)

You should also add a comment for any code updated for a bug fix. Include your
issue tracker number. (If such code is refactored completely, all comments in
the replaced code go away.) While you can simply include such a comment in a
commit log message (using Git for example), It is better to comment all
modified code so the reader knows what was changed, why, and when. (Remember
that updated code often means you need to update the automated tests for that
code.)

Unclear code should not have what comments added. Instead, fix up the code!
(This is known as refactoring.)

[Linus Torvalds (the inventor of Linux and of Git) said this (in the kernel code
style document): “Comments are good, but there is also a danger of
over-commenting. NEVER try to explain HOW your code works in a [what] comment:
it’s much better to write the code so that the working is obvious, and it’s a
waste of time to explain badly written code.”]

While in general I agree with that, if you cannot come up with elegant
solutions that are short and obvious, what comments are better than nothing.
Maybe your comments will inspire others to invent more elegant (clearer) code
for your task. Here’s an example of a good what comment for a regular
expression that is not obvious:

// Format standard email dates, for example:
// Fri, 13 Mar 2020 11:29:05 -0800:
String RFC5322DateTimeRegExPattern =
"^(?:\s*(Sun|Mon|Tue|Wed|Thu|Fri|Sat),\s*)?(0?[1-9]|[1-2][0-9]|3[01])\s+
(Jan|Feb|Mar|Apr|May|Jun|Jul|Aug|Sep|Oct|Nov|Dec)\s+(19[0-9]{2}|[2-9][0-9]{3}
|[0-9]{2})\s+(2[0-3]|[0-1][0-9]):([0-5][0-9])(?::(60|[0-5][0-9]))?\s+
([-\+][0-9]{2}[0-5][0-9]|(?:UT|GMT|(?:E|C|M|P)(?:ST|DT)|[A-IK-Z]))
(\s*\((\\\(|\\\)|(?<=[^\\])\((?<C>)|(?<=[^\\])\)(?<-C>)|[^\(\)]*)*
(?(C)(?!))\))*\s*$";

(I bet even Linus would agree to have a comment here!)

(End of part 1)

Feedback is welcome!

--
Wayne