Are code comments important?

By | July 19, 2008

From the very first day I have heard about Agile development and I have been hearing things like “code comments are not such a good thing

The main idea behind that is that the code should be self explanatory; giving functions good names and splitting concerns into different functions.

But what about the “why”; why this certain code is written this way? why not do it that way? and this is what I have gone through today!

I was working on this bug I had which resulted with a really nasty Timeout Runtime error!
I instantly remembered that there was some place in the code that had the same functionality, so I jumped to it and found it is doing the same thing….almost!

Why my code isn’t working?!…my code saves the domain object…and that code saves the domain object too! Ok, he is using the repository directly…and i am using the service…so what?!
Being that guy my team leader Muhammed Tobji, who happens to be a really smart guy, I was sure I was on the right track!

After spending sometime struggling with that bug, I noticed a lot of comments above the that line of code of Tobjis, it said:
“Don’t use the service…use the repository…or you will have a Timeout exception!!”
GGRRRRR!!!

It was there! I don’t know how much time I could have wasted trying to find the solution, when the solution was already there! The code was almost cleanly refactored, the name of the functions were logical and self explantory, and yet..that was not enough! there was we still a need for comments because it was exceptional situaion (and software has lots of exceptional situations 😉 )

my conclusion is “use comments”! Be wise though, don’t comment the obvious, but in such situations…please…do post your code comment :)

(thanks Tobji 😉 )

2 thoughts on “Are code comments important?

  1. Mohammed Al-Tobji

    /*
    more than welcome Emad, thanks for the compliment :)
    The real problem is due to some locking behaviour for the nested
    transactions involved on that situation
    although this was not the best solution, but it was the fastest
    to meet the delivery withouht sacrificing the functionality 😉
    anyhow, It seems you have some time window now, so you can investigate thoroughly 😛
    */

  2. eashi

    OMG lol, I brought it to myself! I have a new task now :S

    Thanks again Mohammed :)

Leave a Reply

Your email address will not be published. Required fields are marked *