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

Terms of use

Terms of Use

The use of this site and the content contained therein is governed by the Terms of Use. When you use this site you acknowledge that you have read the Terms of Use and that you accept and will be bound by the terms hereof and such terms as may be modified from time to time.

All text, graphics, audio, design and other works on the site are the copyrighted works of nasscom unless otherwise indicated. All rights reserved.
Content on the site is for personal use only and may be downloaded provided the material is kept intact and there is no violation of the copyrights, trademarks, and other proprietary rights. Any alteration of the material or use of the material contained in the site for any other purpose is a violation of the copyright of nasscom and / or its affiliates or associates or of its third-party information providers. This material cannot be copied, reproduced, republished, uploaded, posted, transmitted or distributed in any way for non-personal use without obtaining the prior permission from nasscom.
The nasscom Members login is for the reference of only registered nasscom Member Companies.
nasscom reserves the right to modify the terms of use of any service without any liability. nasscom reserves the right to take all measures necessary to prevent access to any service or termination of service if the terms of use are not complied with or are contravened or there is any violation of copyright, trademark or other proprietary right.
From time to time nasscom may supplement these terms of use with additional terms pertaining to specific content (additional terms). Such additional terms are hereby incorporated by reference into these Terms of Use.

Disclaimer

The Company information provided on the nasscom web site is as per data collected by companies. nasscom is not liable on the authenticity of such data.
nasscom has exercised due diligence in checking the correctness and authenticity of the information contained in the site, but nasscom or any of its affiliates or associates or employees shall not be in any way responsible for any loss or damage that may arise to any person from any inadvertent error in the information contained in this site. The information from or through this site is provided "as is" and all warranties express or implied of any kind, regarding any matter pertaining to any service or channel, including without limitation the implied warranties of merchantability, fitness for a particular purpose, and non-infringement are disclaimed. nasscom and its affiliates and associates shall not be liable, at any time, for any failure of performance, error, omission, interruption, deletion, defect, delay in operation or transmission, computer virus, communications line failure, theft or destruction or unauthorised access to, alteration of, or use of information contained on the site. No representations, warranties or guarantees whatsoever are made as to the accuracy, adequacy, reliability, completeness, suitability or applicability of the information to a particular situation.
nasscom or its affiliates or associates or its employees do not provide any judgments or warranty in respect of the authenticity or correctness of the content of other services or sites to which links are provided. A link to another service or site is not an endorsement of any products or services on such site or the site.
The content provided is for information purposes alone and does not substitute for specific advice whether investment, legal, taxation or otherwise. nasscom disclaims all liability for damages caused by use of content on the site.
All responsibility and liability for any damages caused by downloading of any data is disclaimed.
nasscom reserves the right to modify, suspend / cancel, or discontinue any or all sections, or service at any time without notice.

For any grievances under the Information Technology Act 2000, please get in touch with Grievance Officer, Mr. Anirban Mandal at data-query@nasscom.in.

New

See all

No notification found.

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

AMC Bridge

@AMC Bridge

April 6, 2023

Mobile & Web Development

327

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.

coding Quality software Software Architecture code readability scalable solutions code comments C++ programming

Disclaimer

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.

AMC Bridge