Code that is also a letter
Technical writing is supposed to be for machines; these six pieces were written to people. Read them for the reader each one has in mind: whoever holds the counting rods, the next programmer, a colleague up all night, a friend remembered, a stranger who opens the source file years from now.
-
Step 1: 九章算術·方田（分數諸術） The Nine Chapters: The Arts of Fractions
可半者半之；不可半者，副置分母、子之數，以少減多，更相減損，求其等也。If both can be halved, halve them. If not, set down the denominator and the numerator side by side; take the lesser from the greater, and go on subtracting each from the other in turn, to find the number in which they become equal.
Long before anyone typed a program, the Nine Chapters wrote one out for a person: halve both if you can; if not, take the lesser from the greater, again and again, until they are equal, an algorithm addressed to whoever holds the counting rods; two thousand years later, a style guide starts from the same courtesy.
-
Step 2: PEP 8 – Style Guide for Python Code (Introduction; A Foolish Consistency is the Hobgoblin of Little Minds) PEP 8: A Foolish Consistency
One of Guido’s key insights is that code is read much more often than it is written.
PEP 8 starts from the insight that code is read much more often than it is written, and tells you to break its own rules whenever following them would make the code harder to read; the PEP it quotes fits a whole philosophy into nineteen lines.
-
Step 3: PEP 20 – The Zen of Python PEP 20: The Zen of Python
Simple is better than complex. Complex is better than complicated.
Nineteen aphorisms written down and a twentieth left for the reader, first posted to a mailing list and still printed by every Python interpreter for anyone who types import this; the network’s numbered series of memos had room for a Christmas poem too.
-
Step 4: RFC 968: ‘Twas the Night Before Start-up’ RFC 968: ’Twas the Night Before Start-up
I twisted my fingers and counted to ten; an off-by-one index had done it again...
Filed among the Requests for Comments with the usual note that ‘distribution of this memo is unlimited’, Vint Cerf’s parody of a Christmas poem ends on the culprit every programmer knows, an off-by-one index; thirteen years later he used the same series to remember the man who had edited it.
-
Step 5: RFC 2468: I Remember IANA
If Jon were here, I am sure he would urge us not to mourn his passing but to celebrate his life and his contributions.
Jon Postel edited the series for almost thirty years and kept the network’s numbers in order, and Cerf praises the documents he left, ‘not only the technical but also the poetic and whimsical’; the last step is three lines that stand where a licence would.
-
Step 6: The SQLite blessing, and “SQLite Is Public Domain” The SQLite Blessing
May you share freely, never taking more than you give.
In place of a legal notice, a blessing at the head of every SQLite source file asks whoever opens it to do good, to forgive and to share freely, never taking more than they give: the plainest proof on these shelves that code can be a letter.