Code Comment - ary

Posted on Jun 14, 2023

Programs must be written for people to read, and only incidentally for machines to execute. — Structure and Interpretation of Computer Programs

Code comments are one of the things which are as conflicted as one’s belief of best programming language. Some believe in no comment at all, some in extensive commenting, some in “block commenting”, and others in “line commenting”. What is right really depends on the situation and the needs. But choosing a good commenting strategy and knowledge of common best practices not only makes your life easy but also the lives of anyone looking at your source code.

code comments be like

There are tonnes of tools like analyzers, compilers, linters, IDEs and what not to take care of your code. But none of them could take care of your comments. Your compiler doesn’t check your comments so there is no way to determine that comments are correct. And that is why you have to care about them.

And this article is all about that. It has some good insights on coding comments. which can help you write nicer comments in your next project.

What not to comment?

First of all, (and it goes without saying) your code itself should be as readable and as simple as possible. You should strive to make your code as clear as possible without relying on comments as a crutch. Only at the point where the code cannot be made easier to understand should you begin to add comments.

Code can only tell you how the program works; comments can tell you why it works. Try not to shortchange your fellow developers in either area.

void foo(int n) {						// function foo denotes depth first search and takes an integer argument n, denoting the index of parent.
	arr[n] = 1;							// arr stores the nodes already visited
	for(int i=0; i<T[n].size(); ++i)	// i denotes the index of child nodes. T denotes tree stored as adjacency list.
		if(!arr[T[n][i]])				
			foo(T[n][i]);
}

void dfs(int parent) {
	isVisited[parent] = true;
	for(auto child: TreeAL[parent])
		if(!isVisited[child])
			dfs(child);
}

See, which code was easier to understand? Even though the first one has more comments but second’s more readable. Adding comments doesn’t always give a positive effect. Hence it should not be used as a substitute for quality code.

“Any fool can write code that a computers can understand. Good programmers write code that humans can understand.” — Martin Fowler

What to comment?

Next is what to comment? What to comments is a thing with some extremely opposing viewpoints (and surprisingly everyone is right). All of the best programmers and project maintainers have different rules of what needs commenting and how should that be commented.

So it’s always a good idea to look into the contribution guidelines/previous work if you are contributing to an open-source project.

Here are some of the things people generally comment:

The Plan

Many developers try to outline their idea with comments before actually coding it. This gives the benefit of not having to remember the whole, already ideated workflow every time.

Description

This might be the most common thing comments are used for. It involves explaining the connected code in plain English (and that means senior devs may find it annoying).

It is a good habit to keep explaining your code keeping your target audience in mind. You may not need to explain working of a simple POST endpoint in a professional environment.

But again, remember, code comments are not a remedy for writing bad code. You should spend a good amount of time simplifying the code, rather than commenting. A classic example: You are not expected to understand this

Resources

Links to standards and other documentation can help readers understand the problem your code is solving. While this information may be somewhere in a design document, a well-placed comment gives readers the pointer when and where it is most needed. Also, it’s a good habit to always give a link to the forum from where you copied a snippet ,as It allows future maintainers to make any positive changes/optimization if they come up later on. Pasting in the URL is much quicker than later finding the reference.

Metadata

Developer sometimes use comments to store metadata about the file, like:

The creator of the original version of the program file
Date when the first version was created
Current maintainer of the program
Who has edited the program file so far
URL of documentation about how to use the program
License

Auto Documentation Syntax

A lot of cool documentation generators use the comments in the source code to automatically generate documentation for the program. Examples are Javadoc for Java, Doxygen for C, C++, etc. Forms of docstring are supported by Python, Lisp, Elixir, and Clojure.

C#, F#, and Visual Basic .NET implement a similar feature called “XML Comments” which are read by IntelliSense from the compiled .NET assembly.

Where to comments?

The top of a program file

It is called the Header comment. It is generally used to store metadata about the file, like who wrote it, who amended it, what the code does, IDE metadata, license, etc.

/* === This file is part of Calamares - <https://calamares.io> ===
 *
 *   SPDX-FileCopyrightText: 2014-2015 Teo Mrnjavac <teo@kde.org>
 *   SPDX-FileCopyrightText: 2019 Gabriel Craciunescu <crazy@frugalware.org>
 *   SPDX-FileCopyrightText: 2019 Dominic Hayes <ferenosdev@outlook.com>
 *   SPDX-FileCopyrightText: 2017-2018 Adriaan de Groot <groot@kde.org>
 *   SPDX-License-Identifier: GPL-3.0-or-later
 *
 *   Calamares is Free Software: see the License-Identifier above.
 *
 *
 */

The above snippet is from a file, Settings.cpp from a project called Calamares. It shows how production level, rich code samples are using header comments.

Above functions/methods

The basic idea of a function is an abstraction. I think a function is a black box that takes some input and produces some output. What is being done in the function can be skipped (sometimes) if one knows what the end result would be.

/* 
 * Takes an object as an argument, with valid username and password string fields;
 * Returns a 48 characters long auth token, valid for the next 24 hours.
 */
const login = ({username, password}) => {
  // ...Some complex login mechanism.... 
  return token;
};

The consumer of the above function would probably never need to understand its internal working as long as it has a high-level idea of what the function needs and what it returns.

And that is why the description of a function is one place comments find great use.

In line

Any “tricky” code where it is not immediately obvious what you are trying to accomplish, should have comments right above it or on the same line with it. Like this one:

Inline comment examples

Final say

Understand what may need comments. Your personal portfolio site probably would not need an extensive commenting strategy, but the javascript library you created would definitely need one.

Commenting thumb rules one can follow while coding can be:

Write the name of the program and its author
What the program intends the code to do
Whether the programmer thinks the code could be better written
Where the program may be incomplete or need updating

I am not an expert in any way (far from that) but I do understand the importance of good comments. And everyone should.

Hope this article helped you understand the reasons why commenting is a necessary skill in computer science. Cheers :)