Paj's Home: Programming: Style Guide

Style Guide

Introduction

Good code is essentially code that is easy to understand. This is subjective and no guidelines can completely specify it. Indeed, experienced programmers have their own individual style. I think the most important thing is to read over your code, imagining you knew nothing about it, and try to honestly assess if it's easy to understand.

Comments

Generally you should use comments that are a paragraph, using some technique to make them stand out. I like this, which works in most languages:

#--
# If name and message were specified, go ahead and update database
#--

Exactly how you use the hashes and minuses doesn't matter. The point is to use a fairly big comment and then have a block of code. This approach is much more helpful than this:

$cnt++; # increment the counter
print "\n" if($cnt % 10 == 0); # print a new line every tenth iteration

These kind of comments are not generally helpful, because you've got the code to tell you that. The main purpose of comments is to give someone an idea of what a section of code does, without making them read through the details.

At the top of each file start with a comment that explains the purpose of the file. Sometimes it's useful to give a high-level overview of the implementation here, but that's not always necessary. If the code works on a database, I often include the SQL code to create the table here. For projects with more than one file, you also need some overview documentation that explains what the compontents are, and the interfaces between them.

Functions

A good approach is to use lots of small functions. Each one focuses on a specific purpose, following a clear step by step procedure. If half the function deals with special cases, bounds checking, error handling and such, consider splitting the function up further. My Vigenere program is a good example of this.

However, some programming tasks are very sequential, and in this case I prefer avoiding functions altogether. For programs around 100-200 lines, this is the most readabile approach. There is a general rule here:

Only define a function if it is used two or more times.

Or at least, you expect that you'll going to use it a second time shortly.

Naming

The general rule with variable names (all names in fact):

The length of a name should be proportional to its scope.

Single letters are fine for short loops (use i, j) and parameters of short functions. I try to follow the mathematical convention of x, y for continuous variables and n, m for discrete ones.
For most variables you want a single word as a name. You can abbreviate this, e.g. msg instead of message, but don't go overboard. Sometimes two words are needed to convey meaning, but I try to avoid this.
Global variables (which should generally be avoided) need to have long names, often I include the name of that section of code, to ensure uniqueness, e.g. htable_root_node.

For longer identifiers, prefer names_like_this to NamesLikeThis. Reserve case variations to distinguish types, for example name C macros LIKE_THIS, and Java classes Like_this.

Avoiding short comments

Sometimes I am tempted to use a short comment to explain an obscure programming construct, for example:

str = reduce(lambda x,y: y+x, str) # reverse the string

But it is much better to rewrite the code, so the code is readable. One way would be to define a reverse function; another approach I like is:

reversed_str = reduce(lambda x,y: y+x, str)

There are times when a short comment is appropriate, but generally long comments and readable code work best.

Efficiency

To some extent there is trade-off between code clarity and efficiency. I've seen some C code which used 15 instructions instead of 20, by using a very obscure while loop. This is worth doing when the code is used a lot, but if that loop was just used once on startup there would be no point in the optimisation. There is an important priciple here:

Premature optimization is the root of all evil.

If you program in a logical, readable way then your code will generally be quite efficient. Once you have it working you may want to apply some optimizations. It's only worth doing these in cases they'll make a real difference - long loops, widely-used low-level functions, etc. Often a clean program structure makes it easy to add features like caching in a nice, readable way. If you do have to resort to obscure while loops to save nanoseconds, put a comment next to it with the unoptimized code.

Random points

Avoid true/false function arguments, e.g. cipher(true, str) - encrypt, cipher(false, str) - decrypt. Better to have encrypt(str) and decrypt(str).
When dealing with files, load them up completely, process in memory and then write to disk. Let the OS handle virtual memory, rather than using the input/output files as virtual-virtual-memory. One exception to this is databases, but you're unlikely to need to write your own DB code.
Use the canonical test. If you want to check if the operating system is Windows NT, the best way is if $OS=="Windows_NT" rather than say if exists %SYSTEMROOT%/system32/drivers/etc. The former is much easier to read, and is less likely to be confused by e.g. someone downgrading from NT.
Write code so it's never more than 80 characters wide, so it can be read easily on a text mode screen. Also, this length limit stops you doing too ridiculous things in one line, which brings us to...
If you can do it on one line then do so. Some one-line constructs are dubious through, for example $file = `cat filename` in Perl is a very inefficient way to load a file.