What Makes for Good Comments? (Part 4 of 4)

[Wayne]

Required Comments

A fourth type of comment is a "required comment". These are the comments you
must have at the top of each source code file. If your code is under any sort
of license or copyright, you can either list the license in the comments or
include a link to the license. (I’ve seen source code file with over 100 lines
of such comments at the top, even when the code is less than a dozen lines!)

What else is required depends on circumstances. You might need to identify the
author(s) who wrote the code and purpose of the code. If any of the code came
from others (taken from StackOverflow for example), include references (a
hyperlink is best). As another example, you might need to include a reference
to a license for your code.

For our course, you must include the purpose of the file (“project x, to do
such-and-such”), the names of all authors, and any collaborations you used (“I
found an example of this at URL xyz”).

Hyperlinks go bad over time, except for a few that are stable for very long
times: RFCs, code references on StackOverflow, and the Internet Archive
<https://archive.org/>. For the rest, include a date retrieved. That can be
useful to find the site from the Internet Archive. (Ensuring your page is
archived there, then using the archived copy for your URL, will keep the links
working.)

Required comments include compliance information, such as what standards the
code must meet. For example, security standards, financial standards, military
standards, etc. There are standards for code that runs on airplanes and
boats. common examples include compliance with the EU’s GDPR
<https://gdpr.eu/> (a European privacy standard) and California’s Consumer
Privacy Act <https://www.oag.ca.gov/privacy/ccpa>. Such comments should
include the name of the standard and a hyperlink, and may include a notice
about by whom and when a compliance audit was last performed. (If not required
to be in the code, audit information belongs in another file, for example
"security.txt" or "compliance.txt", and included in your repo.)

If the code is online or you use online systems to manage the software
development process (code review, issue tracker, wiki), have links for those as
well.

Every organization will have different rules for required comments.

Bad Comments

"Bad comments" should be eliminated. Some examples of bad/useless comments
include “//initialize variables”, “x = 2; //set x to 2”, “num = num + 1; // add
1 to num”, “//Default constructor:”, etc.

Often you can eliminate such bad comments by choosing better names. For
example:

p = n * e + t; // Compute price

can be written as:

price = quantity * priceEach + tax;

The same applies to method names.

Avoid ambiguous comments, for example:

// No file found means all defaults are loaded

That must have meant something to the author, but what? Is this a placeholder
to remind the programmer to do something later, or a statement that some other
code was supposed to load defaults, or something else?

See some comics about comments from StackOverflow.com at
<https://stackoverflow.blog/2021/12/23/best-practices-for-writing-code-comments/#h-memes-and-cartoons>.

Comments are a vital part of your code. Always keep them clear, correct, and
useful. Do not forget to update comments whenever you update the related code.

Feedback welcome! I hope you found these articles useful.

--
Wayne