Don't be a commenting idiot

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.

Advertisements
This entry was posted in Code. Bookmark the permalink.

One Response to Don't be a commenting idiot

  1. Pingback: Tales From The Geek Side » A couple coding pet peaves

Leave a Reply

Fill in your details below or click an icon to log in:

WordPress.com Logo

You are commenting using your WordPress.com account. Log Out / Change )

Twitter picture

You are commenting using your Twitter account. Log Out / Change )

Facebook photo

You are commenting using your Facebook account. Log Out / Change )

Google+ photo

You are commenting using your Google+ account. Log Out / Change )

Connecting to %s