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

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