Comments in code is such an endless debate, so much so that I couldn’t help but share my own arguments on it. So, where do I really stand as far as comments in code is concerned? Hold it for a second. In his best-selling book Clean Code, Uncle Bob, makes the following analogy while talking about clean code : as location is to real estate, so is readability to source code. I totally agree with that statement. With that in mind, let us take a look at some arguments for and against having comments in your code.
There are several arguments for and against having comments in code. Let us start with the reasons why you should refrain from commenting your code:
What having comments in code could mean
- A sign of bad programming – in short, you are not a good programmer! That is a tough pill to swallow. It could be totally wrong but you know the truth about how good you are as a software developer. By commenting all over the place, you are exposing your insecurities as a programmer.
- Laziness – you leave a lot of comments in code when trying to explain what the code does. You should instead write code that explains what it does; in other words, you are running away from responsibility. Variable names, methods and class names should read like a well-written column. Should say what they do.
- Unless your code is a public-facing API, your coding style is probably bad. Again, who am I to judge? The truth however is this: unless you are writing an API that users will have to read through its documentation to use it, having comments everywhere a method is defined is just unnecessary. Adds to the line numbers and crowds the class file.
- You are a procrastinator. Commenting code so that you can come back later to fix something or do it right is a bad idea. The best approach in such a situation is to get it done today or before moving on to the next part of code project.
- Commented-out code – the reason why version control tools exist today is to take away the responsibility of remembering changes from you and me. Commented out code is ugly and should be deleted. If you want to get it back, just get it from your version control system.
When you can have comments in code
You are probably thinking “shut your face Elisha”, how can I not have comments in my code? You are right; you should have comments in your code – at least when you cannot avoid it. Here are the situations that could warrant having comments in code.
- Public Facing API – without comments, you cannot generate documentation. That means your API will be difficult to use by other developers. If you have tried using a library that does not have documentation, you know what the heck am talking about.
- Possibility of something dangerous happening. Perhaps you want to warn a future reader of your code about the risks of executing some code under certain conditions or environments. It really comes down to you; if you spent enough time to think about your code, you wouldn’t need to warn people of your code’s possible explosions.
- Header comments – always on top of the file. I like this because you always get the opportunity to include your name. It shows a sense of responsibility. If you write crappy code, (I hope you don’t), another programmer can easily locate you – they know who you are because you are not a coward. Take some responsibility. Be awesome!
I know for a fact that being told I am a bad programmer is not the compliment I would like to hear, not even from my grandma. The fact is, you have a “way” of writing code and you hold it dear. You believe it is the “right” way just as I do whenever I write code everyday. But what is right and what is wrong about having comments in code? Who calls the shots? I think using your own judgment and learning from experts like Uncle Bob and Steve McConnel can help you see what you are missing.
If you have been flooding your code with comments, do not feel bad. Just re-factor it slowly by slowly. You might even learn a thing or two about writing clean code – just like I did.
That is all I have to say today! If you found this post helpful, please consider sharing it using the buttons below. Thank you and always stay awesome as you write clean code – code that says what it does. See you!
NOTE: If you have not read Uncle Bob’s Clean Code, I highly recommend it. I have no affiliation to the seller of the book.