Three reasons why comment your code is a very good practice
Oscar Andrés Granada Baquero

What about writing code that can be understood without comments?

Yes, there is a place for comments. E.g. if something in your code is not immediately clear or required special attention. If there are rare occasion of this, then it is OK. But if the reader of your code needs comments all the time, it tells me only one thing — you can’t program very well.

If the code drowns in the comments, it becomes just noise. And as it becomes noice, the next guy does not care to keep the comments up to date. And the out of date comments are much worse then no comments at all.

Code reviews are a very good tool in ensuring that the code is easy to understand. If a reviewer asks you what code does, it should tell you that you need to rewrite that particular part of functionality.

And sorry, if you need to document your own code before you yourself fully understand what it does, it just means that you are not very good at writing code. Recently I have found a code that I wrote in early 1990s, it was combination of Assembler (!) and Turbo-Pascal (it was OOP code). And I still could understand it. So if you can’t understand your own code you wrote a year ago, you need to find a different job.

Generally a developer would read comments only if the code is so bad that it makes him really desperate, or if the comments are a very occasion in the code and thus stand up from the background. It is human phycology.

Like what you read? Give Sceptical Meerkat a round of applause.

From a quick cheer to a standing ovation, clap to show how much you enjoyed this story.