Code Zhandwa

Recently Jeff Attwood and a few others blogged about how we probably don’t need a lot of comments in our code, provided we write good, readable and self explanatory code. Jeff’s blog post definitely proves a point and the example he has put forward to prove his point sounds correct as well.

I came across Dan’s blog entry later the same day and realized that he too makes a good point. Both sound absolutely correct to me - and equally incorrect as well.

We all assume that we live in a day and age of rapid development and fast internet access everywhere. That, in my opinion is dangerous to assume. Let’s look at the example Jeff posted at his blog:

r = n / 2;
while ( abs( r - (n/r) ) > t ) {
  r = 0.5 * ( r + (n/r) );
}
System.out.println( "r = " + r );

This was transformed into a better solution by Jeff into:

private double SquareRootApproximation(n) {
  r = n / 2;
  while ( abs( r - (n/r) ) > t ) {
    r = 0.5 * ( r + (n/r) );
  }
  return r;
}
System.out.println( "r = " + SquareRootApproximation(r) );

Dan on his post converted this to:

/**
 * Approximate the square root of n, to within the specified tolerance,
 * using the Newton-Raphson method.
 */
private double approximateSquareRoot(double n, double tolerance)
{
    double root = n / 2;
    while (abs(root - (n / root)) > tolerance)
    {
        root = 0.5 * (root + (n / root));
    }
    return root;
}

According to me, Dan’s version is the better one. As it at least gives you an idea of what could possibly be going on here.

I have a different story to tell here. I was called upon to fix a bug (since I was the only Java guy around) that was causing a lot of pain for some people. The code was pretty to look at. Most methods had comments and variable names were understandable as well. But then I reached a point where I was totally lost.

There was this method, which was doing something. It was following some algorithm, the code even mentioned the algorithm’s name (which I don’t remember right now :)). It was hardly 10 lines of code, but probably the most archaic, wierd piece of code I have ever seen. Now, as Dan said, if you know which algorithm is being used, then just Google it and understand the code.

Unfortunately, that was not possible. Yes, you heard it right. No Google. As a matter for fact, no active net connection as well. The code was on a server machine, placed in a high security - no code goes in or out - kind of environment. There was no way I could have jotted down some information about the method and later check it out over the net for references and solutions. Nothing. nada.

So I was there, trying my best to figure out what’s happening. Just knowing “Newton-Raphson” doesn’t help. In cases like these, “better, understandable” code doesn’t help as well. The only thing that I wanted to know was what the hell was going on in that method! And I had absolutely no help, whatsoever.

Finally, I had to sit down, write the whole algorithm down mathematically on paper, understand its objective in life, consult with the business behind the application and figure out what was wrong in the code.

All I wanted was 2-3 lines of “code commenting”.

I see people commenting almost every line that they write. Some people suggest the 3:1 rule, where you write 3 lines of comment for every line of code you write. All used to sound totally ridiculous to me - till that day. That day, I just wanted some English in between all the code.