Program documentation – Variable names

29 07 2008

One of the things that helps improve documentation is good variable names. If you are working with financial systems don’t call your variables A, B, and C. Likewise, if you are doing a client service system don’t name your variables carrots, peas, onions and apples. Yes, it makes an interesting recipe, but that’s about all.

I remember once when we had to have some code recreated from source. The generated code was full of variables named A1, A2, A3, …. It was a thorough pain in the neck. In order to make the code usable, maintainable, we had to work through the code and figure out what A1 was, what it did, how it was used, and then give it a useful name, a meaningful name. Then work through A2, then A3, and finally we got to A4178. (Or was that A7841? Whatever, it took a LONG time!) But, when you have a critical system that needs maintenance, you need to do whatever you need to do to keep the business working.

To help you with your variable naming chores, here is this link from Ian Hickman on the 5 rules of variable naming.




2 responses

31 07 2008

I would like to make wallpaper of this post for the cubicle of the idiot who wrote the reports I have inherited.

1 08 2008


Knock yourself out! Smother him in the stuff. Make posters and hang them on the coffee room, by the printer, have your boss read them at staff meetings, hang a copy in your cube, keep a copy handy and refer to it often, frequently open you copy (when the idiot is near by) and read choice phrases from the article as you ponder what is the best name for the current variable. Maybe even take a walk on the wild side and rename variables throughout the code, giving them sense and meaning!

Let us know what happens….

Leave a Reply

Fill in your details below or click an icon to log in: Logo

You are commenting using your account. Log Out /  Change )

Google+ photo

You are commenting using your Google+ account. Log Out /  Change )

Twitter picture

You are commenting using your Twitter account. Log Out /  Change )

Facebook photo

You are commenting using your Facebook account. Log Out /  Change )


Connecting to %s

%d bloggers like this: