Thursday, February 19, 2009

A Code Commenting State of Mind

I've long held the opinion that you write code for the people coming behind you. You hope you can give them something they look at an understand. Sometimes even aspiring to elegance. So I believe the following isn't written to avoid typing.

Commenting is Overrated

Useless comments diminish comment value

In my mind this is the major problem. Comments are seen as a way for people to communicate about a piece of code. Language can be more semantically dense, therefore make it easier to communicate intent. So doing this more can only be good right? I don't think so; I think there are places you are doing odd things where it makes sense to have comments. Comments everywhere mean these valuable comments go ignored. For example:

public Integer sum(List integers) {...}

is as valuable as:

* Calculates the sum of a list of integers
* @param integers - a list of integers
* @return an integer which is the total value of all integers added toger
public Integer sum(List integers) {...}

Commenting often means boilerplate

"Since comments are so communicative we should comment all our code". "All our java has javadoc, it's part of our code style, also we put our braces here". Leads to unnecessary comments that pollute the code base with irrelevant information:

* Determines if cake is a lie using cake context's
* @param whereCakeWasMentioned a collection of cake contexts where cake was metntioned
* @returns boolean - a boolean true if cake is a lie, false otherwise
public boolean isCakeALie(Collection whereCakeWasMentioned) {...}

Ok so a better comment would be:

* Determines cakes lie potential using ratmans lie detecting algorythm http://...

My argument would be -- if ratman's algorythim is that complex then either

public boolean isCakeALie(Collection whereCakeWasMentioned) {


//ratmans algorithm http://..
public boolean isCakeALie(Collection whereCakeWasMentioned) {

If ratmans algorithm is worth mentioning an extracted method will communicate that part of it, or a very minimal comment. When forced to write boilerplate comments for everything, the top most (and useless comment), will be produced.

Code is executed comments are not

While comment maybe appropriate in it's original context, maintaining a comment adds to work load, taking away time from ensuring the method name is communicative of intent and function. Time spent making well crafted comments could be spent making more understandable code. Code must be read to understand it's function, the comment not necessarily so.

Context changes from programmer to programmer

A commenter can not determine the context of the programmer. Should the commenter to explain language features (i.e. regex, bit shifting) that are somewhat distinct from the rest of the language. Does the commenter need to explain patterns (i.e. this follows MVC).

I came to this opinion while working on/with a Smalltalk to Java xmlrpc framework. In our Smalltalk code the comments were few and far between, so when I got to a method and saw a comment I'd often read it if the code wasn't obvious.It's value was made higher because it didn't happen often. The context was almost always something bizarre was going on, and often related to the domain. So my creed became:

If you have to write a comment to explain a method, there's a good chance your method is too complicated. If you're doing something odd that needs explanation then a comment may be appropriate.

This has been written before however, and with a less biased stance at C2 Wiki.


  1. To me, this comes down to rules over personal judgment. We need to have rules for code comments, because we can't trust people to have personal judgment.

    I think that's kind of sad, because people tend to live up to the expectations you set for them (and it can be hard to break through a limiting proposition imposed by rules).

    This TED link has some really excellent points about how we as people need to trust each other's judgment and encourage our collective ingenuity and desire to do good work.

    Since the comments aren't executed they also have a strong tendency to get out of date, tell the wrong story and actually serve to subtract value (opposite of the original intent, and also something that most comments seem to approach).

    An alternate idea which I quite like is to have executable documentation -- some times this takes the form of well written tests (acceptance or unit). Another python alternative is Doctest - these are easily readable examples of how the method should and shouldn't behave. It's locality it very close to the original method, and it's story-telling ability is very strong. This also has the benefit of being executed, thus a strong force to keep it in sync with the current state of the code.

    A good article on DocTest for agile testing can be found at:

  2. In the workplace sense, I couldn't agree more. To me it doesn't even have to be an issue of trust. We all are doing something we are interested in (programming isn't so accessable that people just fall into it). We all want to feel fulfilled, and in my experence doing work you feel is good quality is a good way to get that sense of fulfillment. At least for the eight hours a day you spend at work.

    I think my feelings around this post are that at multiple places that i've worked comments were a requirement at all times, regardless of the value they added.