Tutorial :What is the best comment in source code you have ever encountered? [closed]


What is the best comment in source code you have ever encountered?


// I know the line below is wrong, but it came that way from our IP vendor, and   // the driver won't work if you "fix" it. I've had to revert this change 4 times  // now. Leave it alone, or I will hunt you down and hurt you  if (r = 0) {      /* bunch of code here */  }  else  {     /* even more code here */  }  


// this comment included for the benefit of anyone grepping for swearwords: shit.  


} catch (PartInitException pie) {      // Mmm... pie  


Not quite a comment but a goto label



I saw this comment on someone's code:

// This comment is self explanatory.  

I guess he meant to say 'variable' but the mistake made one funny comment... Think of the circular logic here, and the futility of writing it.


class Act //That's me!!!  {    }  


try {    }  catch (SQLException ex) {      // Basically, without saying too much, you're screwed. Royally and totally.  }  catch(Exception ex)  {      //If you thought you were screwed before, boy have I news for you!!!  }  


Next to a local variable that had to be declared just to pass a constant to a library function:

// This only exists because Scott doesn't know how to use const correctly  


virgin = 0;     /* you're not a virgin anymore, sweety */  


public boolean isDirty() {      //Why do you always go out and      return dirty;  }  


 * ...and don't just declare it volatile and think you've solved   * the problem. You young punks think you know what volatile   * means... why in my day we had to cast it volatile uphill   * both ways, and the code still didn't work! Whippersnappers...  


The original Doom had an engine with static walls that could not move; the result was that all doors opened vertically; nothing could ever move horizontally. I burst out laughing when, after the source code was released, I was looking through the code and saw this in the source file for handling doors, at the start of a big block of commented-out code:

// UNUSED  // Separate into p_slidoor.c?    #if 0           // ABANDONED TO THE MISTS OF TIME!!!  //  // EV_SlidingDoor : slide a door horizontally  // (animate midtexture, then set noblocking line)  //  


Taken from the Quake III source, I stumbled across this in some random slashdot posting. Full source of the file can be found here. It's a particularly fast method of calculating an inverse square root. As for the best comment? It's a common one to be sure, but given that it's attached to the line that does the magic is what makes it great.

float Q_rsqrt( float number )  {    long i;    float x2, y;    const float threehalfs = 1.5F;      x2 = number * 0.5F;    y  = number;    i  = * ( long * ) &y;  // evil floating point bit level hacking    i  = 0x5f3759df - ( i >> 1 ); // what the fuck?    y  = * ( float * ) &i;    y  = y * ( threehalfs - ( x2 * y * y ) ); // 1st iteration    // y  = y * ( threehalfs - ( x2 * y * y ) ); // 2nd iteration, this can be removed      #ifndef Q3_VM    #ifdef __linux__      assert( !isnan(y) ); // bk010122 - FPE?    

Next Post »