sean's place

Useless documentation is worse than no documentation

Jef Raskin [acmqueue.org] has an interesting take on comments. He argues that the idea of “self-documenting” code is a farce; code might sufficiently explain what the it does, but cannot (usually) explain why it does that.

I agree.

There is such a thing as clear code. In some cases, a reader can infer ‘why’ by simple process of reason, but in just as many, if not more cases, the ‘why’ is a mystery. Therefore, code documentation (‘comments’) are important, but not important enough to have simply for the sake of having them. Take these examples:

if (rqstdTrnsfrAmt > MAX_TRANSFER_AMOUNT)
  throw new IllegalTransferException();

// Check if the requested transfer amount is greater than the max
if (rqstdTrnsfrAmt > MAX_TRANSFER_AMOUNT)
  // throw an IllegalTransferException if the above is true
  throw new IllegalTransferException();

Are the comments in example #2 useful?

In this case, we wish to prohibit a transfer beyond the maximum transfer amount. It seems that the code does a great job of explaining this on its own. However, one may rightly wonder why such a transfer is prohibited. How about this example:

// Prohibit transfers above the maximum amount per policy S0P1234.A
if (rqstdTrnsfrAmt > MAXIMUM_TRANSFER_AMOUNT)
  throw new IllegalTransferException();

This example is perfect. It blends clear code with a brief description as to why the code exists. Of thse three, which would you prefer in your own code?

I believe that comments must describe that which has not already been described. Comments are useless if they simply echo what the code already says. These types of comments interrupt code flow and make reading more difficult. Nevermind the fact that useless comments must change as the code changes, requiring twice the effort in making such a change.

In my opinion, comments should only describe the rhyme and reason for code that is unobvious (leave it up to the rational coder to decide what constitutes “unobvious”) and explain the ‘why’ portion if it’s useful to know ‘why.’

Code cannot always be self-documenting. However, isn’t useless documentation is worse than no documentation at all?