Good and Bad Programming Styles

Good programming style

When writing code, there are several things you should bear in mind that will make your code more helpful, both to you, other people working on your code and anyone else who is trying to understand your code. Many are inspired by (or even stolen from) Outstandingstar‘s article on how to be a better programmer.

1. Be Consistent

Whatever coding style you choose, keep it the same right the way through. Don’t be tempted to change it because you think it would look nicer slightly different, some bit of code looks odd because of the way the whole project is laid out.

2. Use descriptive names

Always use function and variable names that describe what they do. This makes your code infinitely more readable than if all your variables are named a, b, c, d. Don’t be afraid to use long variable names to make the name more descriptive, GrossTaxRate may seem too long to be writing out all the time but when you look at your code again, you’ll be hard pressed to remember what GTR means. This is a rule you’re allowed to break, though. For example, “i”, “j” and “k” make excellent loop counters unless the loop counter has a very specific meaning with a better name. Since mathematicians often use them for indexing, your code will be consistent with math papers. There’s also a balance between looking up the meaning of “GTR” (or guessing it from context), and typing out GrossTaxRate in your equations.

It is common practice however to say what your variables are when they’re declared. Something like “int GTR; //Gross Tax Rate” is common, most editors will allow you to search for a specific term, and a quick search for GTR will turn up the line of declaration as the first (well, in most cases at least). However, there is a time where this is not acceptable. If you’re making a library and GTR is some external value, you should really name it GrossTaxRate. The main reason for shortening names is to more easily write expressions using them.

3. Indent

Always indent your code blocks for things like ifs.

if (a>b)
{
printf("a is bigger");
printf("%i is the larger number",a);
if(a>10)
{
printf("and it is bigger than 10!");
}
}
else
{
printf("b is bigger");
printf("%i is the larger number",b);
}

Is much clearer than

 if (a>b)
{
printf("a is bigger");
printf("%i is the larger number",a);
if(a>10)
{
printf("and it is bigger than 10!");
}
}
else
{
printf("b is bigger");
printf("%i is the larger number",b);
}

Be careful to indent a sensible amount. 2 or 4 spaces for each indent are popular choices but whichever you choose, keep it the same.

4. Comment your code

Comments are a short explanation of what each bit of code does, they don’t affect the final program at all but are very helpful when trying to understand your code.

Don’t write how your code does something, write what it does.

 //If LineLen is bigger than WindowWidth we make it equal to it instead
if (LineLen > WindowWidth)
{
LineLen = WindowWidth;
}

Is not very helpful, anyone who can read the code could understand this.

 //Shorten the line to make it fit in the window if its too long
if (LineLen > WindowWidth)
{
LineLen = WindowWidth;
}

Explains the purpose of the code.

This code could be written as follows, in order to avoid having to scroll through pages of code where most of the lines contain only comments, { or }.

 // If the line is too long, shorten it to the window size.
if(LineLen > WindowWidth) LineLen = WindowWidth;

Bad programming style

After being pissed off with my Java teacher, I decided to spend the rest of the course pushing the limit of how bad my programs could get without failing the course. I’ll list some of the highlights here.

• One-letter variable names. Not very imaginative, but a cool side effect is that you can fit more code on a single line. Sometimes you can make pretty complex algorithms fit on a line or two.
• Silly variable name scheme. If you don’t want to use one-letter names, at least use some naming scheme with no relevance to the code. “Alice’s Adventures in Wonderland” is a good start.
• Don’t comment your code.
• If comments are enforced, I’ll give you one hint. A certain book is available as an e-text from Project Gutenberg.
• Lie. Just remember that if you lie all the time, nobody will believe you. Make sure that most variable names and comments are correct, but that the 5% most important and complex code will have misleading variable names and comments lying about the purpose of the code.
• If there’s a simple and fast way to do things, avoid it. I once decided that text output in Swedish would be too inflexible, so I made sure that all messages were handled in Esperanto internally. Of course, this required a large and inefficient class to automatically translate these messages at run time.

How did my crusade go? I got things thrown at me by the teacher, but ended up with an A in the course