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

--- SoupGate-Win32 v1.05
* Origin: fsxNet Usenet Gateway (21:1/5)