Programming Style

Make The Program Readable

This benefits you when you come back later and try to fix, expand, or reuse an old program.

It also benefits others when you share your work with them. It's great to share your programs with others, but you're not doing them a favor if you give them something that they can't figure out!

For most of our examples, we will use hypothetical code intended to center content in a display that is 18 inches wide.

X = (18 - W) / 2

CenteredPosition = (DISPLAY_WIDTH - ContentWidth) / 2

Sometimes you want a big "block comment" that describes the overall task to be accomplished by the next few lines:

' Wait for the Trick-or-Treater.
'
' To be sure that the kid is really there, make sure that we see
' the KidPresent several times in a row (ideally a full second)
' before actually starting.
SStartAgain:
  KidWait = 0
SLookAgain:
  IF KidPresent = No THEN SStartAgain  ' if no kid, start at the beginning
  KidWait = KidWait + 1
  IF KidWait < 20 THEN SLookAgain      ' keep looking until we see kid many times

You can also put a comment on the end of a line, explaining what it does:

  PULSOUT MonsterRoar, 1               ' 10 µs pulse to sound chip; make monster roar

In either case, whenever you come back and change the program later, you must update the comments. If you change the code without changing the comments, the commentary can devolve into lies that mislead you in the future.

You often ended up with lines like X = (18 - W) / 2, and if you left the program and came back to it a month later, you could spend hours trying to figure what you had originally intended.

Things are a lot better now, with most programming languages allowing longer names for variables. Unfortunately, old habits die hard and some programmers still use short names. Yes, I suppose it saves a little on typing, but it makes the code hard to read.

I suggest that you use longer names and take advantage of that length to make them more meaningful.

Isn't CenteredPosition a bit more indicative of the result that we are getting from the calculation? Isn't ContentWidth helping you to figure out what is going in to the math?

It also helps if you name these symbolic values in such a way that they are clearly distinct from variables. E.g., DISPLAY_WIDTH is a symbolic value that shouldn't change, while ContentWidth is a variable that will probably have a different value for every line.

There are two reasons why this is often a good idea:

• It makes the code more readable and understandable.

  Our hypothetical code X = (18 - W) / 2 has that 18 sitting in there. What does it mean? Why not 19 instead of 18?

  You might come back to this program later and spend a bit of time wondering where the "18" came from.

  X = (DISPLAY_WIDTH - W) / 2 Is more meaningful when you read it.

• It gives you a single place to make future changes.

  Since our improved code uses "DISPLAY_WIDTH" everywhere, it is easy to change the program to run on a display that has a different width. Just go to where "DISPLAY_WIDTH" is set up and change it in that one place.

• We're not doing this for efficiency.

  Any decent compiler will keep a pool of literals and reuse them, so you don't save space by refering to a single value. The compiler will use inline values for small numbers, so speed is not an issue. (Heck! It might even optimize that division by two into a shift right operation!)

Don't Over-Design

As a result of this, professionals sometimes over-design a program. This takes many forms:

But these situations are usually rare.

Most of the time, it is better to just get the darn program working, and then to tune it up later - if you need to. Because often the simple approach works just fine and you don't need to further optimize it.

Side note to professionals reading this:

You might be thinking, "If you completely disregard efficiency, you may paint yourself into a corner by writing a program that can't be optimized later." Yes, that is possible.

But not all programs really need to be efficient. For those that do, you should know in advance. If you are monitoring a nuclear explosion in realtime, you will have stringent performance metrics laid out in advance. If you are operating a talking skeleton, the code doesn't have to be that fast.

Lastly, when you suspect that performance will require optimization, you can plan for the optimization and not implement it until it is needed. "Eventually, we'll need to speed up data retrieval by putting a cache here. Let's get it running first, then add the cache when the program does so much work that it starts to slow down."

Don't Overdo This Advice

Here are some examples of how things could get silly of you go overboard: