Thread: The Art of Writing Comments :: Software Engineering

I usually type short, one-line comments immediately after any confusing or contextually-dependant snippet. When I'm done I try to add more detailed comments, but usually not unless someone whines. (I hate writing comments, too). Mostly though, the best comment is a well named variable, in my opinion. Here are some annoyances of mine though:

The Comment Freak:

char * szBuff = new char [256]; /* allocate memory */ <--duh!
for(;*szData; szData++) /* loop thru data */ <-- um, gotchya.

...etc.

The Obscure Commentor:

//...if missalign then do align...
val = ( !((val >> 0x30) & ret) ) ? pz >> val : val >> pz;

The Hungarian Gone Mad:

PCHAR_T pchr_tMixData;
PMX_SIZE pmx_szPmixSize=sizeof(tagPMX_STRUCT_TABLE_DATA);