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.

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: Logo

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

Google+ photo

You are commenting using your Google+ 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 )

Connecting to %s