“Code never lies; comments sometimes do.” — Ron Jeffries
Code should be self documenting, the purpose of classes, methods and variables should be obvious that you can understand it in six months time.
The reason I don’t like comments in code is because you have to maintain the code and the comments. I have seen examples where developers have changed the code but not the comment. When code and comments are out of sync, readers aren’t sure if the code or the comment is wrong. In most cases it’s possible to name the variables and methods for it to be clear what it’s doing, making comments redundant.
It’s easy to underestimate the effort needed to create obvious naming, first attempts are usually not as clear as they can be, you shouldn’t release your first draft. Make the naming clear, so someone who hasn’t worked on the code can read it and understand it.
You should add descriptions to classes and public methods because this can generate documentation. You should document code when you have written unusual code that is doing something odd that people would be tempted to refactor it.
“Don’t repeat yourself. Every piece of knowledge must have a single, unambiguous, authoritative representation within a system.” — Andy Hunt and Dave Thomas
Adding comments break the DRY principle because it creates two versions of the truth, When you create two versions of the truth, the result is a maintenance overhead that drifts apart.
Naming gone wrong
The naming of classes, method and variables should make its purpose obvious, removing the need for comments.
Clear naming of code relies on applying the single responsibility principle (SRP) to your code. SRP means each class, method and variables should have one responsibility. Robert C. Martin encapsulate this well by saying SRP should mean a class should one reason to change.
Reading more about SRP
Common signs you have broken SRP and the method/class is doing too much is when it’s hard to name because it’s doing more than one thing. Names like.
Methods which are hard to name are because the class or method are doing multiple things. This code has multiple reasons to change, hard to test and difficult to understand. Bad code is hard to name.
The truth of code can be confused by the lies in comments — HoskWisdom
Developers think adding comments helps understand the code. My experiences is comments rarely add anything to the code, or they have written comments instead of applying SRP and naming properly.
Comments are like commented out code, it adds confusion and increases the maintenance costs. Every line written has a maintenance cost and the potential to create a bug, the less code and comments the better.
Comments intuitively seem useful, but they are not what many developers think they are. The same qualities that give comments strength are it greatest source of weakness. Comments create two versions of the truth, a maintenance overhead and encourages developers to put less effort into naming. Most developers would be more productive to spend the time on refactoring the code and improving naming.
Most comments in code are written by junior developers thinking they are helping or by bad developers trying to explain their poorly written code.