January 11th, 2005

a look of abject horror, yikes

On Worthless C Comments

So my textbook covers the subject of bad C commenting style. The classic example is
i++; //add 1 to i
but worse can easily be fabricated, like putting the comment in a big flashy box of asterisks. But because of that example, people tend not to really do things like that- especially in code they expect other people to see, right?

I just encountered this litte gem in GnuGo for the TI-89/92+/V200 (was just the TI-89, but I changed that. Yay open source! I also made the cursor work better, implemented handicaps, implemented side selection, improved the endgame code, improved the pass code, fixed a pass-related bug...), in the code global to GnuGo, not the localized code for the calculator:
void genmove(int *i,
             int *j)
/* generate computer move */
{
   int ti, tj, tval;
   char a;
   int ii, m, n, val;
   int try = 0;   /* number of try */
     ...


Let's think about that for a little. Here at the start of this function, there are nine variables being defined. One of them has a name that is a valid English word that represents exactly what the variable means. The other eight are not full words; of them, only two of them are vaguely self-descriptive. So why the fuck does the one that actually adheres to the ideal of self-documenting code get a comment when nothing else does?

*head explodes*
  • Current Music
    Moby- We Are All Made Of Stars