Comment

It includes both excessive and redundant comments.

Sign of Smell

“Comment” is a very special code smell case because it’s not really a “code”, it’s a comment.

Firstly, to show my respect for all the best practices and conventions of each programming language, it is important to note that the code smell "comment" I discussed here is the comment that may not necessarily be present in the code, not the one that might have some impact on the real behavior. For example, some language connects framework features by comments, this is not the case we covered here.

The bible of clean code, called "Clean Code: A Handbook of Agile Software Craftsmanship," states that if you find yourself needing to add comments to help developers understand the intention of a function or method, it signifies that your code is not clear enough.

No comment is better than no comment. — Bater, Chen (me)

This phrase, inspired by "No code is faster than no code," means that the most efficient code is actually having no code at all. Similarly, the best comment for code is no comment at all. Clear code should express its intention itself without additional assistance.

This idea is nice, but in the real world, it can be extremely difficult to do. There are often numerous comments on the project for various reasons.

Reason of Smell

In this section, I will explain several types of comments and why they are considered a bad smell.

Change Log

One common type of useless comment is the "Change Log". In some companies, there may be a rule to record the date, author, and reason for change as a comment above the function or method name.

This kind of information is not 100% useless but should be placed in the document or checked by “git blame”, not a long list of comments.

Some developers even write comments like a personal diary, well, better to not comment here.

Dead Features

It’s actually another smell called “Speculative Generality”, but in comment status.

One day, the project manager came to the developer's desk and informed them that the current feature was no longer required, but there was a possibility of needing it again in the future. In response, the developer decided to comment out the feature.

In fact, we no longer need that feature. Furthermore, it is usually faster to rewrite it to synchronize with the latest version of the codebase when we truly need it again.

Tasks or Steps explanation

When we have a complicated function or method, some developers tend to write comments to better describe each step or sub-task of the function.

If your function is complex enough to require explanations through comments, it is a sign that you should refactor it and make it smaller and clearer.

Refactoring Recipes

To eliminate this smell, it's not simply to delete the comment. Let's see some refactoring skills that match with this "comment" code smell.

  • Rename Method

  • Extract Method

  • Introduce Assertion

Rename Method

When a method name is not clear enough and requires additional comments to describe it, it is better to rename it with a clear name.

Extract Method

When you come across the "Tasks or Steps explanation" comment, the current code might already be violating the Single Responsibility Principle (SRP), which means it is doing too much at once.

In this case, we can consider splitting the original method into smaller pieces by using the "Extract Method" technique.

Introduce Assertion

In programming languages like Java, an assertion is a mechanism used to check and enforce certain conditions or assumptions within your code. Assertions are typically used during the development and debugging process to detect and report errors and unexpected conditions in your program.

When you encounter a comment, remind the developers that the code only works in certain cases. We can replace such comments with assertions.

Reference

https://refactoring.guru/introduce-assertion

Last updated