• Home
  • Don’t write good comments, write good code

Don’t write good comments, write good code


When a new programmer comes to our team, one of the first questions we are being asked by her or him is how come we have no comments in our code. So we have to tell the same story all over again. If I am personally asked I would give the answer that if you had to comment a function or class, that meant that you had given up on its quality, accepted defeat and then have to use English to describe functionality instead of writing clean and clear code.

Header comments

It is not only the issue about the method or class description comments. I come across a lot of “header comments” as the ones that follow:

* Author: Bobby Newport
* Date Created: 31.12.2017.
* Phone: +49 111 1111 111
* Email bobby.newport@sweetums.com
* I created this class while I was in the shower

Every single line here is unnecessary. The information like author and date created is information that we have in our source control. We do not care who created the file ( which we also can see in VSC ) when we can see who wrote each and single line with git blame ( praise ). Phone and e-mail are redundant because what could you do with e- mail and phone of author. You could call them and say their code is bad!? Also I do not care about your personal comments, such as the way you felt when you created some piece of code, whether you were angry or sad if method turned out the way it did or something similar.

I did personal comments in code all the time before. It was my way of therapy. At the time, I thought I needed to unwind in that way because project I was working on contained a lot of bad codes and I gave my contribution to that by writing more bad codes and I was writing personal comments by which I was justifying myself in my own perspective.

I would write comments like these:

/** I hate this function */

/** This function is beyond repair */

/** When I'm done with this class I'm also gonna be done with this career */

/** Just kill me */

I am aware of the fact that I behaved like an idiot. Comments like those do not give any value to the code. Instead of hating my life, I should probably try and fix that part of code that was responsible for my feelings.

Point is not to do this. No-one cares. Do not complain, especially in your code comments. Instead, do something about it and fix it. Those kinds of comments really makes you unprofessional in the eyes of other experienced developers. You do not want that.

Description comments

Description comments are very common. I think (looking at just programming side of things) they are even worse than personal comments. As I said before, when developer needs to use English to describe behavior of code, that means that he had given up on using computer language to do the same. Less experienced developers often do this. They rely on comments to express behavior of source code, instead of using actual code.

There is simple and easy rule you can follow to fix this. If you feel that you need to write comment to describe something, then stop, look at the code and refactor. Refactor until you do not have the need to write a comment anymore. Simple enough.

There is argument for comments. They should be present as a way of documentation of what code suppose to do. Wrong! We do not care what code is supposed to do. We only care what code is actually doing.

There is an argument that comments should be present to explain to future programmer why the old one created that particular function and what his thought process was. Even though this can be controversial, I do not agree that this is necessary. It can sometimes even be counterproductive. Again his thought process should be clear from the code he wrote or at least we can see his source control history. Also to write good comments, you have to be a good writer. It is really not that easy to effectively communicate with your colleagues through comments.

There is an issue that writing and maintaining code is also very expensive. Now you have to worry about changing not only code, but comments as well. Each time you write some new code or have some new idea you have to update the comments. Yeah, that is not going to happen. You will forget eventually to update comment and then you will have misleading description.

This is why I think thought process comments are something you should also avoid.

Docs comments

The only comments I think you should write ( yes, there are good comments ) are not really comments at all in practice, but technically they do belong in this category. I am talking about documentation comments.

* @param Object $object
* @param Clojure $clojure
* @returns array $result

There is nothing wrong with this, especially if you are using language that is not strictly typed, these things help you keep parameters types as well as return types correct.

If your feel your code is too complex to understand without comments, your code is probably just bad
24 Jul 2008 – Coding Horror

What do you think? Do you write comments in your code and why? You can leave a comment here, which is not as bad as leaving comments in code.

About the Author

Follow me

30 year old software developer from Mostar, Bosnia and Herzegovina, currently living and working in Frankfurt am Main, Germany.

Leave a Reply

This site uses Akismet to reduce spam. Learn how your comment data is processed.

{"email":"Email address invalid","url":"Website address invalid","required":"Required field missing"}