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
Previous Post
Leave a comment

3 Comments

  1. Tyanna

     /  September 1, 2010

    I tend to agree.

    I often use comments to denote something that still needs to be done when I’m coding. A nice //TODO: is easy to search on. It also let’s ppl who are using my code know, hey…this isn’t done yet!

    I like it when there is a meaningful comment that tells me WHY a dev decided to do something the way they did instead of leaving it a mystery for the ages.

    What I hate is the documenting for the sake of documenting. When you see a paragraph of text for 3 lines of code, you know something isn’t right, and the code you’re about to look at will probablly make you cry.

    That’s just my two cents 🙂

    Reply
  2. Kyle

     /  January 12, 2011

    I’m fine with “angry and lazy developer” type comments, as you call them. They (1) call to attention that the code is bad, (2) indicate that it will take some time to unravel, and (3) the developer at least had the discipline to not try fixing everything right now.

    I’ve seen plenty of cases where somebody said “oh, this is easy to fix”, ‘fixed’ it (in the ‘obvious’ way) on the spot, and broke everything. (Or if there’s good test coverage, said “oh, this is easy to fix”, played around with the ‘obvious’ fix for 45 minutes, and then decided that it was a Hard Problem, and put everything back.)

    Would it be better to file a bug report? Maybe. For internal “this code is really bad (but it works)” issues, some people don’t like having a bunch of those bugs in the bug tracker. They’re hard to triage: what’s the priority of such a thing? What’s the user impact? What’s the time estimate? Whereas, if it’s just a comment in the code, then the next time somebody’s deep-diving there, they can see that it’s a problem, right when they have the context to fix it.

    I think I also agree with Torvalds that “If you were to need to fix everything before-the-fact, nothing fundamental would ever get fixed, simply because the people who can fix one thing are not usually the same people who can fix another”. If I fix part and leave a nasty comment, then my coworker can clean up that part asynchronously. If I have to get everybody together to fix everything at once, well, blocking I/O and all that. 🙂

    I’m all for “leaving the campsite cleaner than you found it”, but I think in this case a better analogy is re-shelving books at the library. There’s a reason they have signs saying “don’t try to re-shelve books, just put them on the carts and the librarians will do it later”.

    Reply
  3. terry

     /  January 26, 2011

    I only write “angry” comments on my own code. Sometimes that’s all my code is worth. And it reminds me to hate myself for it later, when I do have time time to refactor.

    Reply

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s

%d bloggers like this: