Beautiful Code One Screen at a Time, Part II

Last updated on: October 31, 2014 at 8:09 pm by willduquette

Beautiful Code One Screen at a Time, Part II 2014-10-31T20:09:47-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.

Last week I talked about code being beautiful at the level of individual lines of code in small procedures. But what about longer procedures?

There are a couple of standard rules of thumb for how what a procedure should do, and how long it should be: it should do just one thing, and it should be no bigger than will fit on the screen at once. And note, these dicta date back to when the typical screen was 80 characters high by 24 characters wide.

My own rules are somewhat different. A procedure should do a set of things that are always or frequently done together; and it should be as long as it needs to be to do those things. And then, if it contains segments that are
used in more than one place, those segments should be pulled out as individual procedures.

This means that my routines are often longer than some people’s; but they still have to be understandable. The technique I use is called FIRST/NEXT commenting. I first ran into this technique on a large simulation project back in the late 1980’s (a project in which some of the individual routines were amazingly, absurdly long) and I’ve used it ever since.

Here’s an example; it’s a routine from Quill that packages up a library as a .zip file:

# BuildLibZip lib
#
# lib   - The name of the library
#
# Creates a teapot.txt file for the library, and then packages
# it into /.quill/teapot/* for later installation.

proc BuildLibZip {lib} {
    # FIRST, make sure the lib is known.
    if {$lib ni [project provide names]} {
        throw FATAL "No such library is provided in project.quill: \"$lib\""
    }
    
    # NEXT, save the teapot.txt file.
    set teapotTxt [outdent "
        Package          $lib [project version]
        Meta entrykeep 
        Meta included    *
        Meta platform    tcl
    "]

    writefile [project root lib $lib teapot.txt] $teapotTxt

    # NEXT, make sure the output directory exists.
    set outdir [project root .quill teapot]
    file mkdir $outdir

    # NEXT, prepare the packaging command
    set command ""
    lappend command [env pathto teapot-pkg] generate \
        -t zip                                       \
        -o $outdir                                   \
        [project root lib $lib]

    # NEXT, call the command
    set outfile [file join $outdir package-$lib-[project version]-tcl.zip]
    puts "\nBuilding lib $lib:"
    puts [eval exec $command]
}

The FIRST/NEXT structure is used in the main body of the routine; and if there are loops or if statements with large bodies, it’s used within those blocks of code as well. Here are a couple of things to note about it:

Given any typical syntax coloring scheme, the comments stand out visually and divide the procedure body into segments.
The “FIRST” and “NEXT” keywords make it clear that the comments do not stand alone; rather, each comment is part of an intelligible sequence.

This is useful to the reader, but it’s also a useful reminder to the author that he’s telling a story. When done properly, the FIRST/NEXT comments are effectively the pseudo-code for the procedure.
Each comments heads a block of a few lines of code: rarely as few as just one, and (except for loops and conditionals) rarely more than four or five. Those lines of code will all be related by the comment that precedes, which doesn’t simply mark a point in the procedure; rather, it explains what the next few lines are supposed to accomplish.
Where the block following consists of many individual lines, this is usually because the lines are all very similar to one another: we are doing the same sort of thing many times over.

Remember that the whole point of this is intelligibility. When I go look at this routine, I immediately see (before I read a word) that it consists of five major points; and that to some extent these points (though linked sequentially) are independent. And then, by reading the comments I can easily jump right to the block I’m interested in.

Some style guides I’ve read (style guides written back when programs were rather shorter than they are now) would suggest that I break this routine up into five subroutines with long, descriptive names. With, in fact, names rather similar to the gist of the FIRST/NEXT comments. Then, the theory went, the BuildLibZip routine would just contain the five subroutine calls, and no comments, and would be “self-documenting”.

Which is well and good; but instead of having one code entity to navigate (a procedure) I’d suddenly have six procedures, each with a header comment; and each of which could in principle be called independently. Instead of having one unit of code with a complex but easily navigable structure, I’d have six independent units of code to keep track of. Since the five subroutines are only called by BuildLibZip, I’d have to make it visually clear in some way that BuildLibZip and its subroutines form a single logical procedure.

And that is, in fact, what I’ve done by making BuildLibZip a single logical procedure with FIRST/NEXT comments.

Previous Post

October 31, 2014

The Monster Mash, Just Because

Next Post

November 3, 2014 CT 16: God Not A Body

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

What Christian group emphasizes speaking in tongues as evidence of faith?

Select your answer to see how you score.

Pentecostals Catholics Presbyterians Methodists