If it comes to coding good practices there is no bigger victim of bad understanding than comments. Self-documenting code is a good, widespread good practice nowadays.

Self-documenting code is a code that can be read like a good novel. Where everything is named, and organized in a way, you just have to take a look to know what the code does.

A lot of developers nowadays are aware of this practice and follow it.

But there is a nuance that definitely has to be cleared out. It revolves around using code comments.

For example Fishtoaster points out, his coworker assumes comments something worrying:

A coworker of mine believes that any use of in-code comments (ie, not javadoc style method or class comments) is a code smell. source

Code smell does not have too much meaning, however it implies some negative bias against a target that is followed by some other remarks about comments:

you should use them carefully - Péter Török source

Simply put don't write you're comments CODE them - Rune FS source

So with such statements it was not hard to guess some people polarize to an opinion comments are essentially a bad thing!

It is easier that way, right? Comments bad! Me not use comments! :-) Or: me like comments!

However, there are people, who take the opposite, or try to balance it:

Use comments to explain why you're doing things a certain way, especially if that way may be non-obvious Wouter Buckens source

An argument against comments is an argument against communication - Eric Holscher source

(...) there’s also the Dunning-Kruger effect, in which most junior and mid-level developers think they’re already Senior Architects. They think that commenting is for the newbies and that their code is perfectly understandable because they are already so good.- Eric Jeker source

What I think about commenting code?

Commenting code is definitely NOT a bad practice, and not a code smell.

Today, the most important problem is that some people really consider comments bad, and using them as a sign of weak code. But this is not true at all.

First, when the code has to be twisted, so that your code reviewer will spill some coffee over it, and you can not change it - you should put a comment explaining why, and what happens. Yes, I really think what is also needed sometimes.

I like to use comments also to separate parts of a processing code. Processing code sometimes is long and complicated. Not always using separation with classes and functions helps to make it better. So, comments are a great way to give some understanding what is going on.

So there are situations when comments are required. But it is not only that. We live in a real life. We have time limits, knowledge limits and so on. So, for example, let's say there is a class with well described methods. But you come to the project, and spend several hours to find an answer talking to people, and browsing the code, to understand what does the method do.

You analyze it, and for some reasons decide you can not change the name of the method to become more descriptive. Some examples when it occurs:

• you don't have time to refactor whole project
• other systems use the name, and it is impossible to change it right away
• you don't know how to make it easier to understand with a different name

So you are left with two options mainly for this particular moment:

1) Leave it as it is
2) Add a comment

If you leave it as it is, you, and new developers will spend again some hours to understand the method. So practically speaking the best way is to add the comment.

Maybe there will be time to refactor the project, adjust other projects later on, or figure out better way to handle it. But from the moment you put a comment, you save hours of wasted time for you and your teammates.

So the practical part is really important in such situations, and especially as a person who joins a project, you have the right to improve it's quality, not only by refactoring it, but also by adding appropriate comments.

Sometimes it may be hard to draw the line, about what has to be explained and what not. But like with everything it is something you learn with practice, and you have to give you the right to try it.

Of course, it may face criticism from some anti-comment people (especially these who wrote the code in the first place).

But the most important thing to ask is how to do it better? And if there is no satisfactory answer, that assures you would not waste time again in the same situation, then the comment stays put.