Beautiful Code One Screen at a Time

As I wrote last week, the software’s source code is the design; and that means it needs to be clear and easy to read; and that means it needs to be clear and easy to read at the lowest level, as it appears when you’re looking at a bit of it on your screen.

Here’s an example, one routine from Quill‘s support library:

# lshift listvar
#
# listvar  - The name of a list variable
#
# Pops and returns the argument from the front 
# of the list stored in the variable.

proc ::quill::lshift {listvar} {
    upvar 1 $listvar thelist

    set result  [lindex $thelist 0]
    set thelist [lrange $thelist 1 end]

    return $result
}

This is a Tcl procedure that removes an item from the head of list and returns it, updating the list in place. I won’t explain how it works, because I’m teaching aesthetics here rather than Tcl programming. But here are some things to note:

• The routine has a short header comment that tells you what you really need to know: what the procedure is supposed to do, and how you call it. In a more complicated procedure it might also detail any gotchas or constraints. In this case it’s a simple Tcl procedure, and a competent Tcl programmer won’t need any more.
• The body of the procedure is indented. This is standard practice for Tcl as it is for most other programming languages; the body of code then resembles an outline.
• Blank lines (“white space”) are added to break the procedure up into logical units. In this case, there are three units: setup, computation, and returning the result; and the three units are clearly visible.
• The tokens in the middle part are aligned in columns. Sometimes this makes it look nicer; sometimes not.
• This formatting is consistent with the rest of the code in the project.
• Color is used to highlight different elements of the code.  The header comment is brown; standard Tcl commands are green; variable references are blue.  That isn’t the color scheme I usually use (I had to apply it by hand), but it’s the case for most programmers that code comes in colors.

The essential point here is that my eye knows where it needs to go to understand the code. The comment is concise, and visually sets off the procedure from its predecessor.  The different pieces of the procedure are clearly visible.  I can see what goes in, what goes out, and what happens in the middle.

More than that, I’m following a conventional style of naming, indentation, and other formatting for Tcl code.  Most languages have a well-established proper style (some, like C, have several competing ones).  If there’s one, your code should use it; if there are multiple, you should pick one and stick to it; and whether you follow the standard scrupulously or you define your own conventions, you should be as consistent as possible.  Consistency of formatting allows the meaning of your code to stand out, for anyone used to your formatting style.