Beautiful Code One Screen at a Time

Last updated on: October 25, 2014 at 8:00 am by willduquette

Beautiful Code One Screen at a Time 2014-10-23T23:10:37-05:00 willduquette

LOGO Patheos Explore the world's faith through different perspectives on religion and spirituality! Patheos has the views of the prevalent religions and spiritualities of the world.

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.

Software Development

software development

Previous Post

October 24, 2014

Marty Robbins: Old-Fashioned Cowboy Music

Next Post

October 26, 2014 An Apology to Weathervanes

Browse Our Archives

Select a Category Admin App o' the Morning Ask the Dogmat Believing Thomas Bits of Fiction Blasts from the Past Bootstrapping the Interior Life Catholic Mom Christian Living Deep Thoughts from the Doghouse Dominicana Evangelii Gaudium Interviews It Was A Dark and Stormy Night Links to This and That Lumen Fidei Meme Watch On Writing Operation Gratitude Pedant Errant Photography Quill Random Barkings S'Mary's World Shakers of Salt Software Development The Dog Whistler The Dogmat Sez Third Orders Thomas Aquinas Uncategorized Vikings at Dinos Woof Guide to Cinema Woof Guide to History Woof Guide to Literature Woof Guide to Obscure Catholic Music Woof Guide to Philosophy Woof Guide to Popular Music Woof Guide to Technology Woof Guide to Theology Words I Wish I'd Written Works For Me

Select a Month September 2016 August 2016 June 2016 May 2016 April 2016 March 2016 February 2016 January 2016 December 2015 November 2015 October 2015 September 2015 August 2015 July 2015 June 2015 May 2015 April 2015 March 2015 February 2015 January 2015 December 2014 November 2014 October 2014 September 2014 August 2014 July 2014 June 2014 May 2014 April 2014 March 2014 February 2014 January 2014 December 2013 November 2013 October 2013

TAKE THE

Religious Wisdom Quiz

Who was the king of Israel known for his wisdom?

Select your answer to see how you score.

Saul David Solomon Hezekiah