Topics In Demand
Notification
New

No notification found.

Useless Code Comments: What Comments Are Better to Avoid and Why
Useless Code Comments: What Comments Are Better to Avoid and Why

April 6, 2023

327

0

Software development consists of many cyclic steps and stages. At every stage, different people plan, perform, and approve work, which makes code writing important but hardly the only part of a quality product creation. Hence, not only code writers should understand code, but also team leaders, technical leaders, architects, and project managers. 

Programmers often change projects and come across code written by someone else. And comments are one of the mechanisms for understanding and maintaining code. Team leaders, technical leaders, architects perform code review tasks and can faster and easier get to know the functionality being checked if the code contains appropriate and structured comments. Project managers, in their turn, are responsible for the quality and content of final artifacts, which include code documentation. It is very easy to create with the help of automatic generation tools if there are code comments that correspond to set standards. 

That’s why this article will be of use to the majority of software development participants: developers, testers, technical leaders, and project managers. 

Why code comments are necessary 

Everyone who has ever written code and can call themselves a programmer will proudly say: good code does not require explanations. And I partially agree with it, but only with the part that you really need to write good code. 

In reality, we can often see variable names like tempVar, function names like myMathFunc, and others, which have no sense. It means that a person out of context will spend much time trying to understand what functional part the code performs. Such code will require much more time to maintain. For example, to fix functional defects or refactor. 

But writing good code is not enough. 

There is a long list of software industries that require writing comments by default, such as a public Application Programming Interface (API). It includes public class interfaces, an interface modeled after the REST API, and other APIs used by external users. Such an API needs comments describing what the API does, what arguments it accepts, what data it returns, what exceptions it throws, and so on. 

For example, a product company with its own R&D will write code comments to make maintaining the existing software cheaper. At the same time, a service company is required to provide documentation for the code it develops, so in this case, comments are the must-have as one of the final artifacts. 

Types of code comments 

Many types of comments are used not only to explain code but also to perform certain functions, as in Bash or HTML. In this article, I will deliberately not delve into the intricacies of programming using certain technologies. 

We will focus on the documentation and explanatory comments. 

Every time we see a function or class after a two-week vacation or when we come back to fixing defects in an existing part of the application, we sit and try to remember what the function does. As a result, we conclude that it is not needed at all and can be deleted. Documentation comments help avoid such a problem. Comments of this type describe what a function does, what arguments it accepts, what it returns, and what exceptions it can throw. They are most often used for API classes and a set of free functions used by one or more application modules. You can see an example of the documentation comment in the C++ language below: 

" "

 

Documentation comments should always be written in a specific format that the integrated development environment (IDE) and the automatic documentation generator can unparse. 

Explanatory comments are used inside function blocks and explain what happens in specific software algorithms. See an example of an explanatory comment below: 

" "

What comments are worth writing, and what—should be avoided 

Despite the fact that comments in code are useful and provide an opportunity to increase the productivity of work on software, I still divide them into those that are worth writing and those that should surely be avoided. 

Worth writing: 

  • Copyright comments in a file header of the source code. Code always belongs to someone, and you need to indicate it. 

  • Interface description—a public REST API interface, class interface with the description of public methods, description of global constants if there are any in a project, description of functions. Any functionality used by your teammates or other development group members should be documented so that it is clear what a specific function or method does. 

  • Description and explanation of algorithms. If you use complex mathematical approaches or branching mechanisms in your software algorithms, I recommend writing comments to explain the steps of the function, the default values for variables, and anything else that will help you understand code. 

  • TODO or FIXME comments for the post-development process—refactoring. There is always a lack of time to write code perfectly. And often, we just make it work and extend the technical debt list. In addition to describing tasks in the technical debt, I recommend using keywords defined by your team to describe what should be done in specific code areas. 

Better to avoid: 

  • Senseless comments. For example, you write variable initialization before initializing a variable. This comment does not give any additional meaning; it is not worth writing. It’s better to describe the default value you initialize the variable with. 

" "
  • Duplication of commit messages in program code headers. Let’s say you make a commit to the version control system with the explanatory comment Fixed issue #1234. Removed duplicating data during an input geometry initialization and write the same comment at the beginning of the program code file. Most companies already use Git, which can capture comments, changes, and anything else related to your code. Therefore, do not write such comments. 
" "
  • Comments for other project participants. For example, John saw a magic number in the code of a function that Shelly had recently written and added the comment: Shelly, do not use the magic numbers. There are plenty of tools for manual code review; use them for such purposes. Or just write in a messenger what and where should be corrected. 
" "
  • Comments that describe the function and variable names. For example, the variable is called mD. It is better to give a name of the variable that will explain its purpose rather than adding a comment that only inflates the size of the program code and the number of lines that need to be scrolled to the required place. 
" "
  • Accusative comments about other—current or former—project participants. Don’t do that. It’s better to add a note to the technical debt, fix the problem yourself, or ask others. 
" "

Conclusions 

Everything that happens in the world of software development is, in one way or another, the result of intellectual activity. Therefore, a decision about what is bad and what is good falls on each of us and is a production link. Every opinion counts, and every person should rely on common sense when making decisions. Write conscious comments with the understanding that they should make life easier for people who will work after you and should reduce the cost of code maintenance for the business. 


That the contents of third-party articles/blogs published here on the website, and the interpretation of all information in the article/blogs such as data, maps, numbers, opinions etc. displayed in the article/blogs and views or the opinions expressed within the content are solely of the author's; and do not reflect the opinions and beliefs of NASSCOM or its affiliates in any manner. NASSCOM does not take any liability w.r.t. content in any manner and will not be liable in any manner whatsoever for any kind of liability arising out of any act, error or omission. The contents of third-party article/blogs published, are provided solely as convenience; and the presence of these articles/blogs should not, under any circumstances, be considered as an endorsement of the contents by NASSCOM in any manner; and if you chose to access these articles/blogs , you do so at your own risk.


© Copyright nasscom. All Rights Reserved.