trip logs / gnuvola

Trip Log 2017-08-19 h07 -- Indices Style Upgrade Part 2

This trip log entry is the second in the “indices style upgrade” series, and the first to look at an individual patch in the accompanying tarball (patch 1, to be exact).  Patch 1 is internal w/ a (satisfying) negative delta.  Why “satisfying”? 

│Fools ignore complexity.│
│Pragmatists suffer it.  │
│Some can avoid it.      │
│Geniuses remove it.     │
│       -- Alan Perlis   │

So on the surface (if you are a Perlis fan — and you should be!), this change smells of genius.  Woo hoo!  But, let's keep our heads (and humble heart) and look closer to try to understand if such gloating is truly warranted. 

The first layer under the surface is the textual description of the change, embodied in the “commit message” (visible at the beginning) of the patch.  Here is the commit message excerpted, w/ the title decoded (the ‘=20’ and such are due to the patch being in valid ‘mbox’ format, which was defined before Unicode existed, back when dinosaurs roamed the earth bla bla bla...):

[tl-mkindex int] Use ‘sort/car<’ more.

* sub/tl-mkindex (sort/car<): New proc, moved to top-level from...
(consult-db sort/car<):
(interesting-elements): Use ‘sort/car<’.

The first half of the title, in square braces, tells us: (a) the change regards the ‘tl-mkindex’ program; and (b) it is an internal change.  OK, no problem.  (That much we know from the patch-set overview, before.)  The second half is a sentence in the imperative mood of the form ‘V OBJ ADV’, i.e., verb, object, adverb.  [Aside to cagers everywhere: Another sentence of this form is “Open eyes now!” :-P]  In the imperative mood, the subject of the sentence is implied.  We understand the subject to be the programmer (or anyone who might wish to climb inside a programmer's brain, such as yourself, perhaps). 

A program is a kind of recipe so the verb and adverb are easy to understand (e.g., "Use more chocolate" is V ADV OBJ).  Still...  What is this ‘sort/car<’?  Why is more of it desirable?  How does the change in the source code actually achieve this goal?  All good questions! 

To answer these, let's look at the rest of the commit message for clues.  Fortunately, it is only three lines — fewer lines, less daunting, that's for sure!  Similar to the title, it also has structure.  The first line starts with asterisk (‘*’, U+2A), followed by the relative filename ‘sub/tl-mkindex’ (comprising the directory ‘sub’ and the program name ‘tl-mkindex’, unsurprisingly).  The rest of the first line, as well as the subsequent lines, have one of the forms: 


where ‘ID’, ‘ID1’, ‘ID2’ are all “identifiers” or names of programming elements; and ‘TEXT’ is either a sentence in imperative mood (line 3), or something that almost achieves sentence-hood (starts w/ capital letter, ends w/ punctuation), but falls short of full grammatical correctness (lines 1 and 2). 

“Hey, ttn!  Speaking of falling short, you missed an opportunity to harp on the recipe metaphor when you said ‘programming element’ instead of ‘ingredient’.  Tsk tsk.  Get your rhetorical game on, man!” 

Ah yes, well, erm...  The truth is that all analogies have limits and if we want to deepen the program as recipe metaphor into a proper analogy, we need to defuzz a bit and introduce a precision that some people might find weird and others wonderful.  (How you react to this precision defines the limit of the analogy for you.) 

In the past, I assumed anyone reading my spew would be a programmer and thus fall into the “wonderful” reaction, but these days I strive to write for non-programmers as well.  Still, the topic is what it is and I suppose if you're still reading, you have the stomach (yuk yuk) to at least accept the possibility that what you might initially taste as weird, can actually be wonderful once you get used to it.  So, here goes (impatient readers can probably skip forward to the “BTW” below)... 

In a recipe, there are ingredients — each a noun (plus adjectives, usually) — and preparation steps — each a verb (plus adverbs, usually).  These nouns and verbs are collectively the “recipe elements”.  When talking about changes to a recipe, it's common to say “use more” (or similar) for the ingredients (nouns), but for the preparation steps, it's more common to use the verb directly.  For example: 

“Want to know how I personalized this banana muffin recipe I downloaded from the Internet?  Two changes:  Use one-third less sugar.  Also, don't add the sugar after all the other ingredients.  Instead, add half the sugar before the other ingredients, and half afterwards.” 

Note that the ingredient “sugar” is named as OBJ in all three sentences relating to the change.  In the first, which describes a change to the ingredients, the V-ADV is “use less”, and in the other two, which describe a change to the preparation steps, the V is “don't add” and “add”, respectively.  In the latter two, the effective change is expressed in the ADV (in this case, as a change to when to V the OBJ).  No big deal, right?  Hearing this description and looking at the original recipe, another person can easily figure out and follow the modified recipe. 

Similarly, in a program, there are nouns (non-executable data) and verbs (executable code), collectively called the “program elements”.  The weird (or wonderful) difference between recipe and program is that, in a program, the verbs are unconstrained by physical reality; program authors are free to define the meaning of “fancy verbs” to embed nouns, adjectives, adverbs, and other verbs.  This is verbing to the max. 

“But ttn, haven't you heard?  Recipe authors can and do define fancy verbs.” 

Yes, this is true.  It's absolutely possible for recipe authors to stay firmly in the real world and be inventive at the same time.  But what is the probability?  Although the difference in mindset is mostly a matter of degree, quantity is its own quality, like they say; programmers think in terms of fancy verbs all the time and this tendency has profound consequences. 

Anyway, returning to the patch, the relevant consequence of this weird (or wonderful) difference in mentality is the deliberate choice of “program element” in the explanation above, and more to the point, the deliberate choice of placing that program element (named ‘sort/car<’) in the third sentence's OBJ position.  This is quite abstract, so for comparison, here's the banana muffin recipe modification expressed w/ this mentality: 

“Want to know how I personalized this banana muffin recipe I downloaded from the Internet?  Two changes:  Use one-third less ‘sugar’.  Don't ‘sugar-add’ after all the other ingredients.  Instead, rework ‘sugar-add’ as ‘sugar-add-half’; do ‘sugar-add-half’ before the other ingredients; do ‘sugar-add-half’ afterwards.” 

Here, the verbs are “use” for the ingredient ‘sugar’; and “rework”, “do not”, and “do” for the fancy verbs ‘sugar-add’ and ‘sugar-add-half’.  Stylistically, the “also” is dropped (redundant) and the recipe elements are quoted.  This is starting to look like the commit message!  A complete transformation would be: 

Customize banana muffin recipe.

Original downloaded from the Internet.

* recipe (sugar): Use one-third less.
(sugar-add-half): Rename from ‘sugar-add’;
rework to use 0.5 ‘sugar’.
(other-ingredients-add): Use ‘sugar-add-half’
twice, once at start, once at finish.

Here, although the fancy verbs ‘sugar-add’ and ‘sugar-add-half’ are named as identifiers, they still function conceptually as the OBJ of the sentences.  The new term “proc” (procedure) is another way to say “fancy verb”.  The tightened title, asterisk, and words “recipe” and “rename” round out the stylistic changes.  Hey, this looks similar to the patch 1 commit message, what a surprise!  Let's look at that again, shall we? 

[tl-mkindex int] Use ‘sort/car<’ more.

* sub/tl-mkindex (sort/car<): New proc, moved to top-level from...
(consult-db sort/car<):
(interesting-elements): Use ‘sort/car<’.

BTW, if you're still reading, kudos!  I imagine reading the preceding section can be quite a challenge (it was somewhat of a challenge to write), and it doesn't help that grammar is one of the dryest subjects around... 

I'll now explain one last detail about the commit message format, specifically the organization of the identifiers (‘ID’, ‘ID1’, ‘ID2’ — remember them?).  In addition to naming program elements, when written between parentheses, they indicate a particular location in the program elements hierarchy.  To “resolve” the location, you first direct your attention to the “root”, then navigate “down into” the first element, and continue navigating “down into” subsequent elements, one at a time, until there are no more elements to consider. 

If there is only one element, we say that location is “at (the) top-level”.  You can think of it as “URL for program elements” (by analogy, for this site: root, top-levels art and trip logs, deeper locations gnugo.el’ screenshots and August trip logs.)  For program elements, the root is the filename (which exists in the filesystem — another hierarchy) where they are defined. 

So, back to the commit message.  We see ‘sort/car<’ — a procedure apparently — as explicit OBJ in title and third line, and as identifier in the first and second lines, i.e., ‘ID’ and ‘ID2’, respectively.  In the first, it appears by itself between parens, i.e., at top-level.  In the second line, it appears after (and thus, “in” or “under”) ‘consult-db’. 

Effectively, the parenthesized identifiers alone in those two lines describe the motion of ‘sort/car<’; the textual description is, strictly speaking, redundant.  However, it's nice that the text provides this cross-check; the more we can confirm inference of intent w/ statement of intent, the more trust we feel.  I'll write more on trust, later. 

OK, enough for now. 

In this trip log we started to look at patch 1, mostly by covering a lot of foundational ground in the area of commit message decoding and how weird (or wonderful) that can be.  In the next (of this series), we'll do some further cross-checks (commit message vs actual patch), ponder the nature of change a bit, and reach a conclusion on the merit of patch 1. 

Copyright (C) 2017 Thien-Thi Nguyen