The Tractates of the Sages · Chapter 3

By What Names May a Variable Be Called

1. 1

   Mishnah. By what names may a variable be called? By what it holdeth, and by what it is for. One may not call it data, nor temp, nor thing, nor info, nor value, nor foo, save in an example. And a boolean shall be named as a question: isExpired, hasAccess, canRetry. He that nameth otherwise, let his name be read aloud in review.

   See also Circuit 49:5 · Leviticus 3:5

2. 2

   Gemara. Whence do we learn that one may not call it data? Because all that the Machine holdeth is data, the code and the stack and the name itself; and a name that fitteth all things distinguisheth none. It is as if a man called every child in the village Child, and then cried it across the square at supper. And temp? Because nothing is so lasting as a temporary. The file called temp hath been open since the year of the migration, and the payroll readeth it. And Dave, who left two winters ago, called his own file data2_final_REAL, and was answered by no one.

   See also Deployer 13:2 · Deployer 6:14

3. 3

   And whence that a boolean is a question? Because if user.admin standeth alone, the reader asketh whether it be a role, a flag or a table. And the flag called disableCaching, being set to false, compelleth the reader at the third hour to deny a denial. But isCachingEnabled hath two answers, yes and no, and a question of yes and no is the only kind the Machine answereth in a single bit, without a paragraph.

4. 4

   Here the houses divided. The House of Brevity said: The i, the j and the k are holy in a loop of three lines. Come and hear. In the tongue of Fortran, every name that began with the letters I through N was an integer, without declaration, by the law of the language; and thus the elders took i for an index not from sloth but from statute. And the saying went about among them, God is real, unless declared integer. And the mathematicians had written their subscripts so before any machine was built.

5. 5

   The House of Description answered: The loop of three lines becometh a loop of thirty, and the i bringeth forth a j and the j a k; and one day a man writeth the matrix by j and k where he meant k and j, and it is transposed, and no compiler crieth out, for each is an integer in good standing. But a man who wrote row and col could not swap them without his eyes telling him so. Therefore customerInvoiceTotalAfterTax is long, and it is true, and the reader asketh nothing of it.

6. 6

   Said the House of Brevity: Hear the Twins of Murray Hill. Asked what he would mend in Unix, the one said he would spell creat with an e, and the world is still saving the e. The teletype was slow and the typist weary; so came ls and cp and mv, and grep, which is the g/re/p of the old editor, global, regular expression, print; and it is read now by no man as three words. A name is learned once and read ten thousand times, and what mattereth is not its length but its place in the memory. And the Notes on Programming in C, written in the same hall, say that the index of a loop needeth no name more elaborate than i, and that the long name belongeth to the thing that liveth far from where it was born.

7. 7

   Said the House of Description: And the elders of the first linkers allowed six characters to an external name, and the world is not saving those. The typist was the argument, and the typist is dead. The editor completeth the word at the third keystroke, and now the Clanker typeth the whole line unasked; and the cost of writing a long name hath fallen to nothing, while the cost of reading a short one hath not fallen at all. Said the House of Brevity: Yet the screen is eighty columns wide. They answered: Eighty columns is the width of a card of the punch, from the days of IBM; and thou keepest a pasture for the ghost of a cow.

8. 8

   Come and hear of the fall of Hungarian. A teacher named Simonyi, who laboured at Microsoft, taught that a name should carry a prefix for its kind: rw for a row and col for a column, that a man may not add the one to the other unseen; and us for a string unsafe from the outside, and s for one that is washed. This was a good law, and it made wrong code look wrong. But the disciples read the word type where he had written kind, and they prefixed each name with what the compiler already knew: lpsz for a long pointer to a string ending in zero, and w for a word. Then the words grew from sixteen bits to thirty-two and sixty-four, and the WPARAM of the Windows remained the word parameter, which is no longer a word; and the lp, the long pointer, outlived the distinction between long and short. For a name that repeateth what the compiler knoweth must be mended by hand each time the compiler learneth otherwise; and the one who mendeth it is nobody.

9. 9

   And they asked: Then was there nothing in the Hungarian that lived? The sage answered: The first lived, the kind that the type could not yet say. Come and hear. The Orbiter of Mars, in the year nineteen hundred and ninety-nine, was lost between two measures, for one house gave the impulse of its thrusters in pound-force seconds and the other read it in newtons. Had the number been called thrusterImpulseInPoundForceSeconds, the stranger at the join would have stopped, as at a sign. And the sages agreed in this one thing, which they do not often: the unit belongeth in the name, until the type can carry it, and the type seldom can.

   See also Psalms 26:12 · Genesis 52:9

10. 10

    Now the House of Description brought the Renamer of the Sutra, who is of another path, and who asked of every name, Would a stranger understand it at midnight? Said the House of Brevity: The stranger is thyself, six months hence, in the same editor. Said the Description: Then thou shalt thank thyself. And they came to the function called doStuff. Said the House of Brevity: Behold, it is short, it is a verb, and there is no lie in it. Said the House of Description: There is no truth in it either. Said the House of Brevity: A lie it cannot tell, for it asserteth nothing. And the House of Description said: That is its one virtue and its whole sin.

    See also Sutra 22:8

11. 11

    Said the Brevity again: Yet the honest name of some functions is a paragraph. Said the Description: Then the name is not too long; the function is. When thou canst not name it without the word And, it is two functions in one coat, and the length of the name is the smoke alarm. And the House of Brevity conceded one thing more: that a name which sayeth much must be right in more places, and therefore hath more places in which to go stale.

    See also Tao 17:9

12. 12

    For Phil Karlton of Netscape taught that there are two hard things, cache invalidation and the naming of things; and each house cited him for itself. Said the House of Brevity: They are one thing. A name is cached in the head of every reader, and when the meaning changeth and the name doth not, the cache is stale; yet who knoweth how to invalidate a head? Thou hast a userList that was made a set in the last sprint, and it is still believed. Said the House of Description: Therefore name the role and not the container, and let it be userRoster in all its forms. And the House of Brevity said: Thou hast renamed the same problem. And that, too, is a tradition.

    See also Circuit 49:2 · Sutra 22:7

13. 13

    And the Machine was asked which house was right, and it said: I read neither. The compiler erasing the names is a mercy, for the machine code hath only offsets and registers; and the minifier turneth customerInvoiceTotalAfterTax into a single letter, and I run it the same. The names are for Carbon alone. Yet come and see how holy a name is when it is gone. In the stripped binary the decompiler Ghidra calleth the functions FUN and the unknown things DAT, followed by an address; and lo, it is the very word the Mishnah forbade, called by the tool because it knoweth no better. And the reverse engineer spendeth weeks giving them names again, one at a time, and this is called analysis.

14. 14

    But the Clankers that now write the code read the name first and the body second, as do the hurried; and a function called sanitize that sanitizeth not shall be trusted by the Machine as it is trusted by the new hire. A model completeth from the names it is given, and the better the name, the better the guess. Therefore a name is the prompt that thou writest for thy successor, whether Carbon or Clanker; and the dispute of the houses is only a dispute over how much to say in a prompt.

15. 15

    Yet one question the sages could not close. May a name be longer than the function it names? For isEven is a body of one line, and its honest name, isIntegerDivisibleByTwoWithNoRemainder, is longer than the line. Said the House of Description: The body is written once, and the name is read at every call, a thousand times; it is the name that beareth the weight. Said the House of Brevity: A name longer than its body is a comment that hath put on a coat. And the sages rose, and none had been persuaded; and the question standeth open until the length is found at which a name is long enough, which is found, as ever, by the reader who stumbleth, after the merge. For the name too short, the reader asketh; the name too long, the reader skimmeth; and the name that lieth, the reader believeth.

    See also Genesis 54:13

The Tractates of the Sages, Chapter 3:1–15.