Log in

No account? Create an account
color cycle (slow)

Kistaro Windrider, Reptillian Situation Assessor

Unfortunately, I Really Am That Nerdy

Previous Entry Share Next Entry
On Worthless C Comments
a look of abject horror, yikes
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*

  • 1
I hate books that try to push a sense of coding style on the reader, other than the blatantly obvious. Yes, boxes with asterisks are stupid. And why the heck does this code insist on using /*comment*/ when it's a lot saner/easier to use //comment? /**/ is too much work.

Speaking of poor style of commenting, in my Int. C++ class last semester, the course curriculum was all hot and bothered and insisted that all functions be preceded by a huge fucking ugly "doc box" that had the aforementioned stars and slashes and all sorts of needless nonsense.

It really bothered me when I had a program with an assload of tiny functions, such as:
double absolute(double num)
{if(num<0)return 0-num; return num;}
(compressed for readability)
...and I'd have to triple the function length just to add the stupid comment box. What do you think this function does, Sherlock?!

I noticed that the only one (of the *eight* being declared?) that got commented was also the only one that got initialized.

And doesn't that book scold such coding "technique" for using those "meaningless" names (i, j, ii, ival, etc.)?

#define ABS(k) (((k)<0)?(-k):(k))

Comments are to be used wherever appropriate, and that's not for every function or line. Some things really do describe themselves...

// comments are only valid in C++; /* foo */ is the required format for a comment in C. There's no C++ compiler for the TI-89/92+/V200, so I use C. There's actually a good reason there's no C++ compiler: C++ is a much slower and more bloated language than C. cout << "Hello World" << endl; actually takes 40K because of the incredible pain that is ostream...

My calculator only supports a version of BASIC, but a friend of mine showed me a program that he'd written on his. For some bizzare reason, the entire thing was written with no new lines whatsoever; apparently the colon performs the same function, while also making the program absolutely impossible to read.

  • 1