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.


On Importance of Good Method Names and Paying Attention

I spent a somewhat frustrating hour at work today trying to plot a straight line on a chart using a framework that shall remain nameless. I quickly had the slope and the y-intercept worked out and all I needed were two x values to plug into the equation to calculate some points. I already had another series plotted on the same chart and just picking the minimum and maximum x values from it was sufficient for my causes.

Naturally, I could do the legwork of figuring the min and max myself, but why do the work when the framework can do it for you? I poked around and found a couple useful methods: FindMinValue() and FindMaxValue(). I had assumed (based on Intellisense and lack of code docs) that they would return the values I needed. Then a couple things taught me that wasn’t so at all:
1. I used var to declare my variables, so I didn’t notice that the functions in question are returning integers.
2. I was wrong in my original assumption. Those methods aren’t finding and returning the min and max values. Instead, they’re returning indices into the array of points in the series, pointing me to the location of the min and max values.

I guess technically the method names didn’t lie: they are “finding” the location of the values for me. I still found that to be counterintuitive. In my opinion, FindMinValueIndex() would’ve been better.

So, the lesson is: pay attention, don’t assume anything, and if you ever release an API framework, try to be as clear as possible about the intent of your methods when you name them.