Gunjan Doshi

I was recently asked, “When is it ok to add code comments?”. We then talked about explanation vs. justification.

Code should be self-explaining. What the code does, should be obvious by reading the code. If you have to add comments to the code, to explain what it does, then it is a code smell.

On the contrary, you may add comments to answer the question: “why does the code do what it does?”. It is ok to add code comments, when, you have to justify some special scenarios or awkward business rules.

I got to admit, I hardly add comments to my code. By using test-driven development, my code usually talks to me: lots of small self-explaining methods with lots of tests keeps us all happy. Patterns like specification pattern can also be used in these special conditions.

Tags: No Comments