The Comment Rant

For years I have done one of the most painful processes in software development. Re-coding/fixing someone else's program code. Now all programmers prefer their own "obviously" superior code to another's but that's not what I'm talking about. Today I'm seriously irked by the fact that very few coders try to write "readable" code. The reason why readable code is good should be apparent to anyone who's had to work with someone else's, but if your not sure what I'm talking about here is a scenario that you really just have to live through before you understand it.

Lets say you've been coding for a few years and you see the following lines of code

for (int x=0;x<10;x++)>Index(x);
}

Now through basic C++ you can figure that its for loop that will go through 10 times and pass the x value into a class method, where something will presumably happen or act on it.

The problem? It means nothing to you, if this was apart of some critical software system this wouldn't tell you shit. Sure you may be able to trace the class method and figure out what's going on but it still won't tell you about the magic number (10) in the for conditional section or what purpose the variable x serves. Now this is a simplified version made to prove a point, but if your one of the few who hasn't had to deal with this just imagine this type of coding on a large scale application. Don't believe it happens? It does.

Now there are tons of tips and even more excuses on how to approach/avoid this problem. Since the ability to read everyones coding style probably isn't a good option, here are a few tips I wish more programmers (even myself at times) would do more often

- Use variable names that mean something, this is easy to over look when writing code constructs you've done a couple of hundred times. (i.e. the x in the for loop)
- No Magic Numbers (Use constants or enumerations)
- Clever things need to be commented on (you probably won't be as clever 3 months down the road when you stare at the code blankly and neither will the next person who reads it)
- Code like someone else is going to read it, I know it sounds dumb but it forces you to code for readability and function.
- Be consistent, programmers tend to mix their preferred language coding styles (habits they've formed recently) with their basic coding style (habits they've formed when learning to program). It's maddening, stop it ... no seriously stop.
- Don't comment to make code look pretty or fuller, comments should be useful to someone who isn't you, i.e. they need to tell someone else what your trying to accomplish and more importantly how your doing it. Dumb comments don't help they just make other programmers glaze over useful ones.

Now before you give me the whole, "that takes too much time" bit the bottom line is that you've learned to code this way because its a habit. So the only way to fix it is to make this a habit, the speed portion will come with practice, now go a more enlightened code ninja.