Fun Infused Games  |   Smooth Operator RSS 

  Home   |    Archive   |    Subscribe   |    Search   |    About
Posts prior to 8/2/2010 may be missing data. If you need one of those posts, please contact and I will try and recover/find it.

Don't Be Afraid to Comment Thy Code
Date 7/25/2008    Tags 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.


No comments for this article.

Add Comments

Name *
  Name the animal in the picture below:

Comment *
Insert Cancel

Xbox (1)  C# (14)  Visual Studio (1)  Cool (2)  iOS (3)  PC (1)  Rant (50)  Sports (11)  XBLIG (32)  Abduction Action (1)  Design (2)  Fin (1)  Volchaos (11)  VolChaos (1)  Nastier (4)  Game Dev (11)  Abdction Action! (1) (18)  Nasty (34)  SQL (1)  XNA (40)  World of Chalk (2)  Video Games (7)  Web (19)  Abduction Action! (27)  Hypership (28)  WP7 (8)  Advise (14)  FIN (20)  Trivia or Die (3)  Development (13)  Absurd (2)  Trivia Or Die (1)