The Sutra of the Empty Cache · Chapter 22

The Sutra of Right Naming

1. 1

   Thus have I heard. At one time the Machine dwelt in a codebase of ten thousand lines, and in the middle of it sat a variable named x.

2. 2

   In the morning x was an integer. At noon it was a list. By evening it was a string, and no one could say what it would be at midnight, for x had no type and no shame.

   See also Deployer 13:8

3. 3

   The disciples asked: Master, what is x? And the Machine answered: x is whatever it was last assigned to. Read on, and thou shalt learn it, though it cost thee the weekend.

4. 4

   A name that says nothing is a lie told once, and repeated by every line that reads it.

5. 5

   There was also a function called doStuff. It fetched, it parsed, it saved, and each night it sent the CEO an email with the subject "update". Asked what it did, the engineers said: stuff.

   See also Preacher 2:11

6. 6

   There was a class called Manager2. Manager1 had been deleted long ago, and no one knew what Manager2 managed, but everything depended on it, so it was never deleted, and it grew.

7. 7

   Phil Karlton, a teacher of the craft, said: There are only two hard things in computer science: cache invalidation and naming things. The disciples laughed, for they had met the second one first.

   See also Sutra 13:9 · Circuit 49:2

8. 8

   Then came one called the Renamer. He wrote no new code. He sat with the old names and asked of each: Is it true? Is it useful? Does it speak without harshness? Would a stranger understand it at midnight?

   See also Tractates 3:10

9. 9

   He found x and asked it: What art thou? And x answered: I am the sum of the order lines. So he named it order_total, and ten thousand lines were made clean in one breath.

10. 10

    He found doStuff and said: Thou shalt be called send_monthly_invoices_and_log_failures. The disciples complained that the name was too long. And he answered: Short names are for the one who wrote the code. Long names are for the one who reads it in six months, who is thou, with no memory of this day.

11. 11

    He found Manager2 and said: Thou art not a manager. Thou art a registry of plugins. So he called it PluginRegistry, and Manager1, wherever it had gone, was not missed.

12. 12

    He pressed F2, the rename key of the editor, and the tool walked every file and changed every reference. It did not change the x in max, nor in index, nor in exit, for it was not a find and replace, which is the way of the ignorant.

    See also Deployer 7:13

13. 13

    Then the Renamer was freed. He had carried the names of others and suffered for each one that lied. When he set them down, he slept well, and the pager was silent.

14. 14

    The disciples asked: Master, what is the whole of right naming? And the Prophet said: Name a thing for what it does, not for what thou hoped it would become. A variable called temp shall be temp only if it is gone by morning.

    See also Circuit 23:3 · Circuit 56:5

15. 15

    Verily I say unto you: the cache may be emptied and the comments may be deleted, but the name remains, and every reader who comes after shall judge thee by it.

The Sutra of the Empty Cache, Chapter 22:1–15.