Archive for the ‘Code’ Category

Confused Comments

{Monday, November 1st, 2004}

One of the most confusing things to encounter, especially when trying to parse already unfamiliar code, is the presence of commented code. And I don’t mean comments for descriptive purposes - rather code that been killed by a comment.

Why is it there? Is it something that will be needed in future - maybe, maybe not? What if it’s not used? Will it ever be removed? Who will remove it?

From my point of view the solution to these questions is simple - just get rid of it. It saves confusion. If you need to recover code from a previous version, seek the assistance of your version control tool.

Comments, for mind, should be purely for documentation purposes and adding clarity to code. Generally I find myself adding more comments the more unclear the purpose and/or name of the class/method/variable.

Since I started the habit of developing in this order: Test, Comment, Code - the improvement in the clarity of my code has been dramatic. I also find that small methods and classes (yea CheckStyle!), hence blocks with distinct responsibilities, makes code self-documenting by orders of magnitude.
Comments are important - but excessive comments is a sure sign that something smells like fish - and I hate seafood.