Are code comments important?

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 😉 )