Like this article? We recommend
Comment Rot
The single most scary thing about comments is the way they "rot". Just this morning I found the following line in a piece of open source software:
extern char* string_find(char*, int); /* defined in psc.c*/
Which is useful and interesting, except that psc.c no longer exists. They've renamed the files since they wrote this. Fortunately, it proved fairly easy to locate the function I needed, but it illustrates the most dangerous thing about comments. As the system evolves, it becomes increasingly unlikely that the comments and the code actually refer to the same "truth."