Comments in the code can be useful in some cases but most of the time the concept of comments is being abused. Too many comments imply a few bad things about your code quality:
Trust Your Code
It means that your code is not as readable as it should be.
Your code should describe your intention on its own, without the need of external mechanisms as comments. By over-commenting your code you admit that another developer can’t understand it just by reading it.
This is where you should ask yourself “How can I make my code reflect the comments’ intention, so it will be readable and understandable on its own?”.
Keep It Clean
It clutters your code with redundant lines.
Many times when I look at a page of code, there are mostly comments and a few lines of actual code. When a developer can’t get a glance of two code blocks in a row, and has to page down and up between them, it will be harder for him to read and understand it.
Keep It DRY
Many times comments break the DRY (Don’t Repeat Yourself) principle.
They duplicate knowledge in your application and by this they require specific maintenance, which makes your code a lot harder to maintain. Here’s an example of a comment which breaks DRY:
Imagine yourself that in one year we want to change the function identity to get also hashes. Now we have to change both the comment and the line which throws the error. We duplicate our knowledge of what the function receives as arguments, and by this we double the changes we need to make to our code in order to alter its behaviour. It is even worse if only one change is made – code only or comment only. In this case, we confuse and misguide the developer.
Keep It Safe
Developers may simply ignore comments when they occur too often in the code. Since most IDEs color comments in a certain color, it is easily identified by human eye and ignored. If most of your page consists of comments, don’t expect anyone to thoroughly read comment line 23 out of 80.
If a developer may ignore our comments, there is (at least) one obvious conclusion: We should never, in any case, put important knowledge of our code in a comment.
There is a much better way to keep our world safe – use tests as means of communication between developers, not comments.
When I’m coding anything which is crucial to the application I immediately create a test that will fail if for some reason someone breaks it. This, with a combination of a Continuous Integration server which will run the tests on each deploy and fail it unless they all pass, gives me the confidence that no one will be able to change this code without having a second thought about it. Yes, I do it even for simple things as constants, when they are important enough. Of course a comment could become handy and makes sense in such case, but I would not trust a crucial constant with just a comment – I would back it up with a test.
I used constants as representation of the simplest knowledge in our application, but the same goes for other behaviour aspects such as expected argument types.
I am not totally against comments but I think that sometimes we tend to put too much responsibility on their shoulders. Comments are not a replacement for clean, readable and well designed code and in some cases may even harm these concepts. We should use comments only when we have no other way to convey our intention, and they should be short, rare and very clear.
The important thing is to never trust comments to guard your code against unwanted changes – This is exactly the reason test exists.