Search This Blog


Thursday, March 20, 2008

Comment on Why? Why?

So, there seems to be a major consensus on code documentation. From the comments on The Single One Tip to Comment Your Code, it seems that everyone agrees that the source code comments should not focused on how. But whether the why should be commented was an issue of contention, . My opinion is that even the why shouldn't be commented, and if you really have to write down the purpose of your code, then maybe there is a code smell in your code.

Let's take a contrived example. Supposed that you have a method that calculates the sine of a variable. But unlike the sine function in the standard library provided by your framework, it can't handle the case when the pass-in variable is a multiple of Pi. But it does not matter since everyone knows that the sine of multiple Pi is always 0. To workaround the limitation, you implement the following wrapper function, and of course, some comments so that your colleagues will not get bamboozled:

public double SineWrapper(double x)

if(x%Math.Pi==0) //this is needed because MySpecialSine(x) can't handle x=0
return 0;
return MySpecialSine(x);

In this case the comment is needed simply because there is a bug in the function MySpecialSine. Comment is there to explain the why of the source code. But if a programmer can't deduce the why from the context that surrounds that particular piece of code, then maybe there is a bug, or at the very least you may need to rewrite your code so that it is self explanatory. Not just in terms of its working, but of its purpose as well.

One exception to the above rule is that when you are dealing with a third party component that you can't modify the source. The component is buggy and so you need to implement an awkward workaround. The of course you need to comment on it. But this reflects the imperfectness of this world and is undesirable. It's much like the trade-offs you make; you don't want to make them if things are within your control.

Comment on Why? Only when you have to workaround the limitations you have no power over to change.


Anonymous said...

I don't think that example works, as many people I believe would see the proper solution would be to:
throw new InputCannotBeZeroException() or similiar, making the code self documenting again, the integrity is bumped up a notch in some cases with the framework or IDE telling the programmer beforehand that the exception can be throw; which is more intuitive than having to dig into the code after you've realised it fails.

I find a good time to comment is simply when logic gets confusing and you see no value in farming it out to self descripting classes/methods, a common but extreme example of this is when you have regexs inline, it's nice to leave a simple english comment above the regex for those less fluent in regex.

Chad Smith

Mick Bennet said...

I think you missed the point on this one. You are arguing against the WHY when it relates to specific issues. You are not arguing against the WHY for the purpose of an entire method, class or module.

These are the WHYs that are important and should be commented. However, in your example, the mini-WHY should be commented too. It may be a performance-enhancement rather than a code smell. You would somment it as such of course so that no well-meaning maintenance programmer 'fixes' it.

Anonymous said...

hm.. luv this thread!