Why Are Comments Important?

Around three months ago, I was shocked looking at some newly added code in one of our applications. It was naked. Not a single line of comment whatsoever!! I asked the person who wrote it to explain the code and it turned out that the code is indeed very cleverly written. I’d rate the code as top notch if only it had comments. When I demanded an explanation, it turned out that he thinks commenting is an utterly boring task. We had a small chat and after explaining how difficult it is to maintain the code without comments, he agreed to add comments, albeit reluctantly. I saved a copy of the code before he added comments.

Back to present: An end users had an issue in the existing application and also had a change request to the functionality. It was to be assigned to the person who wrote it originally. I sat with him and pulled the copy of the code I had saved. He had trouble understanding the code and asked himself, ‘what am I doing here?’, a couple of times. He eventually figured it out and when we pulled the code with comments, he agreed that it was way easier to figure out what was going on with comments.

This is not a one off case. I’m sure this is the deal with most of the IT world. If it is difficult to understand one’s own code just after a couple of months, imagine what the life will be for another person trying to support it after you are gone. Now, why are comments important?