Tales From The Geek Side

All too often I see code that is commented like this:

/*
Function: foo
foo does baz to bar
*/
int foo(int bar);

This is stupid. It is obvious that the documentation block is describing the foo function. This type of commenting is extremely common and I don’t understand why programmers feel compelled to waste their time like this. I’ve seen this practice required in coding standards! The only time this practice could be considered acceptable is if you are using a documentation extraction tool that can not parse your language. If you are using a tool like that you ought to use something better (or write your own, it’s not that hard). Java has javadoc, for C and C++ there’s Doxygen.