Write helpful code comments or none at all.

Stumbled onto the following comment in some code I'm working on:

//Code updated by Crappy Developer - 06/22/2011. Fix for Prod problem.

This is a terrible code comment.  I would rather you not even put this comment into the code.

First off, I've replaced the name of the developer with "Crappy Developer" to protect their public persona and since that's how they are now known to me.

The comment "Fix for Prod problem" tells me nothing.  Aren't all problems Production problems?  Otherwise, they're not problems.  What was the actual bug?  Under which circumstances was it reproducible?  How did you fix it?  Any tricky business logic involved here?

And then there's the "//Code updated by.."  You might think that giving the date of the fix and the developer's name is at least a little bit helpful, but all of that can be discovered with "git blame."  This clown probably doesn't know "git blame" exists.  I'll have to send him the man page on that.

So the next time you leave a comment in the code, make sure its worth the time of the next developer that might see it.  And make sure they aren't just going to blog about how terrible your comment was.  You're wasting time with lame code comments, so please stop it.

No comments:

Post a Comment