Sunday, June 03, 2007

Comments are mostly a bad idea

As I was saying ever before, comments are unneeded unless you write something not obvious, for example resetting a device in a place, where nobody would expect it. Then yes, comment is necessary to disallow everybody removing the code that is requisite.

The other case of using comments is documenting API. Everybody wants to know, what the function does without reading whole body and studying the code.

But for God's sake, don't try to comment each line of code explaining what it does if it's obvious or even worse how it does. If it seems to you, that the code is pretty unclear in the meaning what it does, do it better and don't vindicate it by long comments. This is often a very bad idea and makes the code totally unreadable and ugly. Beginners often do this, I saw a code that seemed something like this:

function min(a, b)
/* compute minimum by comparing both values and */
/* store the one, which is less than the other into */
/* result variable, which will be finally returned */
if (a < b)
result = a
result = b

/* and now, return the computed value */
return result

Please, don't do that ;), at least don't do that where you are working in team, when other people will work on the same code either in parallel with you or after you leave the project.

Final quotation of Martin Fowler about Refactoring:
Comments are often a sign of unclear code... consider refactoring

1 comment:

Anonymous said...

Well done is better than well said.