Making Good Software

A blog by Alberto G (Alberto Gutierrez)

Written by Alberto G

June 6th, 2009 at 12:23 pm

Comments are evil?

with 8 comments

I have recently published an article called “10 commandments for creating good code“, in which the commandment number 8 says “Comments are evil”, well, as I was expecting this has created some controversy and a few comments have been written in dzone.com and news.ycombinator.com arguing about comments being evil, so I have decided to write this small post where I hope I can bring some light into what I really mean when I say “Comments are evil”.

Code quality scale

I believe most of the developers will agree with the following scale.

  • The worst code is: Bad code without comments.

  • Bad code is: Bad code with comments.

  • The average code is: Average code with comments.

  • Good code is: Good code with a few comments…

  • …but… Great code doesn’t need comments!!!

DRY

First commandment in the “10 commandments for creating good code” is DRY (Don’t repeat yourself), I believe this is the main guideline for a software developer, what most software developers don’t see is that every time a comment is written, you are repeating yourself! Now not only you will have to perform maintenance activities on the code, but you will also need to make sure that the comment keeps its synchronicity with the code. Not a big deal? Well, think in all the other principles you follow when you code, each of the small changes you perform in your code to make it better, like spending time to name a class, moving a method to a different class because it just feels right… are insignificant by themselves, is when you put all them together when you can tell that you have created a masterpiece of code.

Should we use comments at all?

Of course!!!!!!! My mistake was to name the commandment “Comments are evil”, is just a guideline, as any other principle you apply in software development, sometimes we just produce crappy code, for many reasons, we are under pressure, we don’t know the technology we are working with… Then for the love of god, use comments!! There are other times where we have prodcuded good code wich has a few comments, that’s fine, we cannot always look for the perfection. What “comments are evil” really means is that you should always push yourself to use as few comments as possible, not because you are lazy, but because they are not necessary.