The other day I was pairing with my buddy and co-worker Alan Stevens. We were reviewing some code, and at one point he said: “Claudio, those comments are ugly!”. At first I thought he meant how comments were worded, but then I realized he meant the way the comments were formatted:
You can see in the snapshot above that something really stands out, right?
Comments (which include code that’s commented out, but *not* XML Comments) are formatted in my environment in a very nasty way, and that’s on purpose. The thing is so ugly, it forces me to read it and find out what it’s all about:
- It may be a TODO, so I want to make sure it won’t be forgotten (very often, a TODO is dropped in code to indicate some Technical Debt);
- It may be code that’s commented out that should have been removed in the first place, instead of be sitting there as waste, polluting our code base with useless, distracting things. “But what if we ever need that code back?”, one might ask. Well, hello-oh, it’s 2010; people better be using some sort of Source Control System!!
- It may be the means of a developer to explain some poorly written code; most times a simple “rename variable” or “extract method” refactoring can easily remove the need of the crappy comment;
- In very rare situations, the comment is actually useful in explaining the intent of the code, so it’s a good thing that it stands out.
It comes a time when code may be tainted with so much useless comment that the mind just starts to ignore the warnings. What do I do? Just change the coloring to some other new ugly combination.
How about you: do you have similar approach regarding how you see comments in the code? Do you configure your environment so to have the editor visually indicate anything you deem important?
#1 by Mark Wilkinson on November 2, 2010 - 9:15 am
very good tip, will start doing this. Luckily I caught your talks in the past about code commenting itself so I use very little if any comments.
#2 by claudiolassala on November 2, 2010 - 10:10 am
Cool. That also helps when you’re going over code somebody else wrote, though.