Don’t put comments in the code – this is one of the guidelines in the projects. Is it good?

Imagine you are working with legacy code and analyzing one of the functionalities. After many long hours, you are finally done. You feel tired, but happy that you know what’s going on. You want to write a comment with an explanation, but … comments are not allowed! Time passes and a few weeks later you have to fix a bug in the code you analyzed earlier. The problem is that you forgot the details. Again, you have to spend hours trying to understand what is happening …

I think you now understand that a simple comment written in a few minutes can save you hours.

There are more cases where comments can be helpful:

• ‘to refactor’ comment

I mark the code for refactoring. Why? Because when writing new functionality or refactoring – when I work with code, I see a lot of “places” that should be refactored, but I don’t have time at that moment, so I mark them as “to refactor” so I can easily come back to that code later. This works very well for me.

• ‘wtf is going on’ comment

I’m sure you’ve encountered many times complicated logic/code that you didn’t understand. If it’s a really important functionality, leave a comment, come back to it later and ask for explanation.

• explanation (why) comment

That’s the big problem. You see the code and even understand it, but you don’t know why. Why, for example, does the code add a +1 for every tenth item or why does it format the name in such a strange way? Maybe because of older systems? Maybe front-end requirements? There could be hundreds of possibilities. But no one will know for sure … unless we document it in code. I know, we create documentation, but the documentation shouldn’t include details. So one option is to put a comment.

• documenting bad code

We know that code should be self-documenting and express business intentions and requirements. Yes, in an ideal project, it may look like that, but I’ve never seen one. Instead, I have seen projects with code that no one understood, bad code. Why not refactor? Because it takes a lot of time and first you need to understand what is going on. To understand we need to analyze piece by piece and put the results of the analysis somewhere – for example, in comments.

Analyzing bad code containing dozens of dependencies can take days or even weeks, so it’s really a good idea to include documentation, such as comments, to save a lot of time in the future.

Certainly, there are more cases in which it is reasonable to put a comment: you had a bad day and wrote “non-ideal” code and want to go back and improve it or you did not have time to write fully covered tests … and so on.

Summary

I’m not a fan of comments in code and suggest avoiding them because they can lead to bad code – developers write low-quality code and put comments explaining what the code does – this is a bad practice. I think this was the main reason why comments in code are not allowed in many projects. I also think that this type of comment – explaining what the code does should be forbidden unless you have a strong reason.

In project you should agree on types of comments that are allowed or even mandatory, e.g., a brief explanation of legacy code, class/service responsibility, to-refactor tag, etc.

Comments are great because they coexist with the code, and should be used to support/boost the coding.