Are Comments Evil?

I’m a bit late to this party, with the majority of the opinions on the subject having been weighed in last week and the week before it, but after reading Jesse Liberty’s Coding Without a Net post and then Davy Brion’s response to it, I’ve been noodling on my own usage of comments in code and what I think about them.

In the end, I think I have to side with Davy and answer the question of “are code comments evil?” with “it depends”. The biggest argument I’ve read against code comments is that they can easily go out of sync with the code. While I agree and have certainly seen it happen many times, I don’t think that’s a reason to avoid comments. I think that’s a reason to hire developers with better discipline. After all, when a comment is replaced with an extra lengthy and specific method name, who’s to say that some developer won’t come along at a later date and change the guts of the method without updating its name? It really is still the same problem — the developer wasn’t diligent enough.

Don’t get me wrong – I don’t think extensive comments are a viable alternative to good naming conventions or proper designs, but I still believe comments can be very valuable when expressing the motivation behind code being written a certain way (e.g. to work around a bug or to address some design considerations). Properly written comments that detail the “how” behind the “what” can save time that’d otherwise be spent looking up a wiki page or some other document that explained the design. And that’s assuming that there even is such a document.

Used in combination with good naming practices, these comments can make reading and understanding code a lot easier. Where this scheme is pretty much guaranteed to go pear-shaped is if the comments are required. For example, I’ve seen projects configured to fail to build if there is a non-private method that’s missing its XML documentation. The result is not unexpected — every public method is decorated with an auto-generated XML comment that is absolutely obvious and sometimes a bit weird – GhostDoc is pretty good at parsing method and property names into English sentences, but it’s not perfect and produces its share of “Validations the handler” on a method called “ValidationHandler”.

The worst kind of comment in my mind, though, is the “angry and lazy developer” comment. Have you ever come across a section of code where someone took the type to type in something along the lines of “This is horrible. Does this even work?”? If yes, then you know what I’m talking about. It’s when a developer came across some code and instead of figuring out what’s wrong with it and fixing it (thereby leaving the campsite cleaner than he found it, as it were) or asking the original developer, he instead chose to leave a passive-aggressive comment in the code and check it in. The odds of someone looking at that piece of code may be relatively low and the comment will survive days, then weeks, then months. It’s even more fun when an aforementioned undisciplined developer comes along and fixes the code without altering the passive-aggressive comment.

So in the end… “it depends”. As with many programming paradigms, there’s a lot of ways to misuse code comments, but I think there also are ways to use them for good rather than evil and that they should not be abandoned completely. The truth is in the middle, not in the “comment everything” or “comment nothing” extremes.

Advertisements

New desktop specs

I have used a laptop as my main machine for a couple years now. I guess calling it a laptop would be a bit of a misnomer — it is an Alienware m9750, a relative powerhouse for its time, weighing in at 10 lbs and making my car think I’m a bad driver who lets her front seat passengers ride without a seatbelt if I were to put it beside me in the car. It has served me well, but the time has come to move on.

I opted to return to the desktop this time, in part for financial reasons and in part because I would’ve much preferred to just do a few spot upgrades on my laptop… which unfortunately wasn’t much of an option. I haven’t paid attention to hardware in a while, so I enlisted the help of a friend in sourcing out good parts to put together. Here’s what we ended up with:

ASRock H55M Pro Micro ATX motherboard
Intel Core i3-530 2.93Ghz Dual Core CPU
4GB DDR3 1333 RAM
Western Digital Caviar Black 640GB SATA HDD (7200 RPM, 32MB Cache)
MSI N250GTS Twin Frozr 1GB video card

With a couple other bits (such as power supply and a DVD burner, all this lives inside an In Win Griffin case and is hooked up to my existing monitor — a 24″ Samsung SyncMaster 2443BW.

For completeness’ sake, my keyboard and mouse are both Logitechs — a Wave and an MX400, respectively.

It is by no means an ultimate machine, but for just over $800 after taxes and shipping, it’s not too shabby at all.

Here’s a comparison of the Windows Experience Index scores. Old laptop:
WEI of my old laptop

New desktop:
WEI of my new desktop

I look forward to upgrading the hard drive at some point (maybe with some solid state goodness) to bump that score up a point.