Some Comments on Comments

Code comments. You probably have an opinion on when, how, or if they should be used. To me, this debate is as heated as "tabs or spaces." Except, this is probably a more important discussion to have, since comments are visible and there are no automated tools to convert from one to the other (bad comments to good comments, there are some that can remove comments completely if that's your thing). I'd like to set forth my own opinion here for the record.


Now, let me be absolutely clear. The only thing I claim to be an expert on here is my own opinion. I am of the opinion that there is no universally correct answer, but I do believe there is a time and place for comments which I will explain in a second. But this does not take into account all of the reasons some standards exist, it just takes into account my personal beliefs about where comments should exist.

Here is a real slide from my Software Quality Assurance class that I just finished taking based on Clean Code. I expect many of you to know of this book as it has become an industry standard.

I agree with 66% of this slide. Of course informative JavaDocs are fantastic. I agree wholeheartedly that self-documenting code is preferable in all cases. But the first point: "Don't" use comments... I think this is very narrow sighted, and I would like to set forth my opinion on when and why you should use comments.

I think it's okay to use comments if you're explaining why you did something, not how you did something. Code should, in fact, be self-documenting for the people who want to read it, and be documented for the people who want to use it. Expressive code is key, and I find myself failing at this aspect of software development most of all. It all gets compiled away in the end, and the computer doesn't care how it's formatted when it reads it, so you might as well make it as readable as possible.

This is why I think comments about how something is done is useless. If you can't tell from the code, the code isn't expressive. On the other hand, if you write expressive code, but the thought process behind is is a little convoluted, then maybe you want to leave a note explaining why you wrote something a certain way. As long as it doesn't detract from the readability of the code and isn't useless, then it's okay.

So, to boil it down into bullet points for a TL;DR, comments are cool in the following cases (in my opinion):

• Documentation for people who will use your code and don't want to read the many different methods that it might call.
• Explaining why you did something a certain way, not how you did it.

Again, this isn't sage advice. I also believe that nothing is sacred in software development, so it's really subjective and could change. So yeah, I just wanted to get that out there. I also haven't written an opinion in a while, so I figured I would.