To Comment or Not to Comment? The Truth About Comments in Code

 

We were taught that commented code was a bad practice when we started developing. In videos and courses, We saw that many considered it normal, but what is truly correct? Does well-written code really need no comments? In this article, We share the lessons We've learned about this topic, which sparks so much debate in the development world.

 

A Comment Does Not Make Up for Bad Code 

Well-written code should be clear and self-explanatory, with good variable and function names, minimizing the need for excessive comments. Comments can help clarify complex logic or specific decisions, but they are no substitute for good design and organization practices. The real solution to hard-to-understand code is to refactor it, not explain what it does. Always think about who will read your code and make your variable and method names as clear as possible so they can understand what your code does.

 

Good Comments

While well-written code is preferable, there are situations where comments are necessary and beneficial. Some comments are truly worth the space they take up because they help clarify complex logic or decisions that aren’t easily deduced from the code itself. Here are some types of comments that are generally useful:

Explanation of Complex Logic

When the implementation involves complicated calculations or algorithms, a comment can help clarify the intention behind the code. This makes it easier for developers who may need to modify the code in the future.

Justifications for Specific Decisions

If a solution is not the most obvious or involves a "hack," a comment explaining why this choice was made can prevent confusion and aid in maintenance.

Notes on Limitations or Restrictions

Comments that highlight specific system limitations or constraints, such as performance bottlenecks or compatibility with certain library versions, are crucial to avoiding issues during updates or future changes.

 

Bad Comments

Most code that relies heavily on comments falls into the category of bad comments. These often serve as crutches or excuses for poorly thought-out or poorly designed code. They are frequently cluttered as if the developer is talking to themselves, trying to justify questionable decisions.

Misleading Comments

Comments that don’t match the logic of the code or attempt to hide flaws or dubious choices. They can create a false impression of clarity or efficiency, but upon examining the code, it becomes clear that it doesn’t do what the comment suggests.

Overly Long and Excessive Comments

Comments that are unnecessarily detailed and take up more space than needed, often explaining something simple that could be understood from the function name or code structure alone. These comments make the code harder to read by distracting from the actual code.

Redundant Comments

Comments that merely repeat what the code already states clearly. These comments add no value and only make the code longer and harder to read.

Conclusion

The issue of code comments requires balance and thoughtful consideration. Comments should not be used as an excuse for poorly written code or as a substitute for good programming practices. Well-structured code with clear variable and function names already conveys most of the necessary information. Comments should be used sparingly, only to clarify complex logic, justify decisions, or inform about limitations.

On the other hand, overusing misleading, redundant, or excessive comments only makes the code harder to understand and maintain. Instead of trying to "explain" confusing code, the ideal approach is to refactor it so that it is self-explanatory and inherently clear. The real challenge for any developer is to write code that makes sense not only to the current programmer but also to those who will work on it in the future.

Therefore, when writing your code, ask yourself: Is it clear enough to be understood without many comments? If the answer is no, it might be time to revisit the code's design and structure. The ultimate goal should always be to create clean, simple, and sustainable solutions, where comments are a complement, not a justification for poorly designed code.

Lucas Mesquita

Backend | Java | Quarkus | Spring Boot | SOLID | Docker | Git        

---

  

Gabriel Carrijo

Back-end Developer Java | Spring Boot | Quarkus | Microservices | SQL & NOSQL | SOLID | Design Patterns

---