Comments are a means to explain and clarify code. But sometimes it gets over used and turns into lies. The better your code is written, the less you need them. I have heard some people say you can’t write enough comments. I disagree with this. Code with a lot of comments is in most cases bad code, I rather have no comment then to much comments. The perfect code does not need them, and it does not make up for bad code!
Good Comments
There are a few good reasons for comments. One of them is describing the variables and return values in DocBlocks. This might be good information to know when using these functions when you don’t have scalar types available in your version of PHP. They also provide a good and generalized structure to write comments. A DocBlock is the place to put need to know information about your function.
Then there is the reason of intent. For me this is the most important reason to write a comment. To write why a certain decision was made. It’s important that you know why something needs to work like this. If you look back at this code since a long time you need to know why it works like this. Why decisions where made.
There are also some cases where you need to clarify some obscure variables, return values or functions. Its better to make sure those have good and meaningful names. But you are not always able to change it if you use an external library. In that case you can then use comments to clarify this code.
You might also need to write comments to warn for consequences. That you have written something a certain way for a certain reason. And that anyone making changes here need to take that these consequences into account. Its very important to explain the reasons very clearly.
Bad Comments
Most comments are for bad code, sometimes its encouraged to write as much comments as possible. But then people start explaining the obvious. It does not help, and it makes everything only more confusing.
/**
* Gets the first name
*
* @return string Returns first name
*/
public function getFirstName() {
return $this->firstName;
}
This developer has followed the guidelines to comment everything. But why? 3 times the same thing is explained. What if we change a function? Then we also need to rewrite the comments… A good function name does not need explanation. Simple as that. In good and clean code you don’t need to write comments to explain what your functions does.
Also mumbling in comments is bad. Like explaining it in some way that only makes it more confusing or writing more text then the code itself. It serves no purpose then to waste time for the person reading that code. When comments are confusing and not clear, they get skipped.
Then as last, the dreaded commented out code. We live in a world where every developer should use a version control system to manage its code. There is no reason to comment out code and let it rot and stink. Just remove unused code. If you ever need it again you can find it in your version control system.
Conclusion
Comments are not the solution to make code readable. The solution is to write clean code. A comment should be a way to explain reasons and to warn for consequences. But we don’t live in a perfect world and there might be exceptions. If you work on projects where its not possible to follow all the clean code guidelines, then you might need to write more comments then you should, to make up for it.
But still, you should not need to write comments to make up for bad code! You should transform it into good code. Think to code!