Don't Be Afraid to Comment Thy Code
7/25/2008
Rant, Development
(0)
Comments are my friend. I like to leave comments before functions, at the begining of classes, and before any complex block
of logic. If a variable name isn't straight-forward enough to tell persisely what it's for (which is a good thing to have,
but not always possible unless you're okay with things named
PercentageOfUsersWhoOverUseStaticsDividedByUsersWhoLoveYogurt), I comment that too. I'd probably comment a comment if there
was a way to do so.
Some might feel that's borderline too many comments, but I'd rather have too many comments than not enough of them. I've
picked up projects by users that didn't document their code at all. You can pick up what the code does, but not always the
reason why it does something nor the programmer's intentions for doing something some way.
Good code should be self-documenenting they say. Mostly the reason for this rant is because Jeff Atwood wrote about just
this fact on his blog Coding Horror (very
good blog FYI). Certainly he made some good points about self-documenting, but I think he went too far in his hatred of
comment use (hatred is a bit harsh, but then again so am I).
So the idea for self-documenting code is that you should be able to take a look at a piece of code and know what it's
intended to do. If you name your function GetAllContacts(), it's pretty obvious that it will get all contacts. If you do x
= 2, you don't need a comment saying "Set x = 2". That seems pretty logical.
Conversly though, if you've got a block of code that does something all mathematical like in your code, I'd much rather
have a comment beforehand that says what it SHOULD do rather than having to walk through the code to determine what
it does do. The reason for that is two-fold.
First, it's a lot quicker to just read a sentence to determine what a piece of code does. Sure I can walk through it, but
I'd rather not. I still have nightmares from college when they forced us to walk through recursive code. When I close my
eyes, I can still see a function calling itself.
Second, by writing what code should do in the comments, you document what code should do. Imagine if you will that you
write some complex piece of code and then it is used for several months. Now there is some bug in your application and you
have to go back over the code. You walk through this code and figure out what it does. Unfortunately, what it acctually
does doesn't match what it should do. If you had a comment saying what the code should do, you'd realize that the result
you're getting isn't the one you wanted, you'd find the bug right away, and get that promotion and corner office you
wanted. But since you didn't comment your code and the code doesn't error out on you (it returns an answer, just not the
right one), you won't find the bug, you'll be replaced by someone that knows how to document their code, and you'll loath
your new job at the Wendy's drive-thru (but enjoy the free Frosty's until you're reprimanded for stealing food). All
because you wanted to save a few lines that the compiler just discards anyways.
This article has been view 898 times.
|