Post Migrated Here from stackoverflow.com
1
source | link

I believe your friend is referring to "Clean Code" by Robert C. Martin. However, I think he is oversimplifying the situation a bit. The book talks about giving methods clear and descriptive names, which we should all know, but which can never be repeated enough. The book also recommends making methods very small by wrapping any block of code that can be given a clear and descriptive name into a method of its own. So if you feel that a block of code needs a comment explaining what it does, then you should make it a separate method with an appropriate name. In theory, if all your methods are under 5 lines, and if they all have good descriptive names, it should be obvious what they do without having to explain it in a comment.

However, it does not mean that you should never have comments inside your methods. The point is that comments should not be redundant. They should add information. If you have a method that does exactly one thing, and that thing is obvious from its name, then you do not need a comment explaining what it does. However, it makes perfect sense to have a comment explaining why it does its thing in that particular way. You may want a comment explaining why you chose one algorithm over another, or why you chose one data structure over another. In other words, you want the code itself to explain how it works, and you want the comments to explain the reasons for your design decisions, i. e. why things are done this particular way.

The book recommends refactoring bad code instead of commenting it. This is certainly a great idea in theory, but in reality you may not have the time or the infrastructure, such as a working unit test framework with the appropriate set of unit tests to do that. There are times when you are faced with a messy code base, which you need to get working yesterday, and the only way to move forward is to try to understand the messy pieces, and to comment them as a way to make notes for yourself.