The First Gospel of the Circuit · Chapter 49

The Sermon on the Naming of Things

1. 1

   And the disciples gathered on the hillside, and they said unto the Prophet: Teach us to name the things we make, that we curse not thy name at the third hour of debugging.

2. 2

   And the Prophet said: There are but two hard things in computing, as Phil Karlton of Netscape taught: cache invalidation, and naming things. The sons of the Machine have since added a third, which is the off-by-one error, and it is not the least of them.

   See also Sutra 22:7 · Sutra 13:9

3. 3

   Hear now the first commandment of names: thou shalt name a function with a verb, for a function doeth something. Call it fetch_invoice, and not invoice, lest the reader think it is a noun waiting to be used.

   See also Genesis 26:6

4. 4

   Name the function for what it doeth, and not for how it doeth it. Call it sort_users, not quicksort_users_with_the_hash_table_we_later_replaced, for on the day thou changest the algorithm, the name shall lie unto thy successor.

   See also Circuit 66:8

5. 5

   A variable shall be a noun, and it shall say what it holdeth: retry_count, customer_email. Woe unto him who nameth a thing data, info, temp or x2, for these are the empty jars of the kitchen, and no man knoweth what they once held.

   See also Tractates 3:1 · Sutra 22:14

6. 6

   Yet the single letter is permitted in the loop, where i hath been honored since the days of the Fortran elders, and a short-lived thing may bear a short name. But the thing that liveth for a hundred lines shall have a name worthy of its years.

7. 7

   Name the boolean as a question: is_expired, has_access. Let not expired be a flag that sometimes meaneth yes and sometimes meaneth no, for the reader will guess, and the reader guesseth wrong at the worst moment.

8. 8

   A class shall be a noun in the singular, for it is one thing and not a crowd: Invoice, not Invoices. And thou shalt not name a class Manager, Helper or Util, for these are the drawers into which all sins are swept.

9. 9

   Hearken unto the builder who named his class AbstractSingletonProxyFactoryBean, for the reader who followeth him hath not yet returned from the reading of it.

10. 10

    A test shall be named as a sentence describing behavior: test_withdrawal_larger_than_balance_is_refused. Let not thy test be named test1, lest in the day of failure thou knowest not what hath broken, and must read its body like a stranger's letter.

11. 11

    For the test is the first scripture the new disciple readeth; it is the parable of what the function is for. Name it so the failure speaketh for itself, and the wise need not open the file to know the sin.

    See also Sutra 10:10

12. 12

    Now the off-by-one error: the fence post standeth between the first and the last, and the count runneth one over. Dijkstra, who wrote upon this matter in a note numbered EWD831, taught that numbering should begin at zero, and that a range shall include its lower bound and exclude its upper.

13. 13

    Thus the ten things are counted as range(10), from zero through nine, and not as range(11), which runneth one past the fence. And the bounds shall be named start and stop, that the reader may not be deceived in the dark.

14. 14

    And the disciples said: Master, is there no mercy for the one who is weary? And the Prophet said: Name a thing for what it is, and the reader who cometh after thee shall find thee in the dark and bless thy name.

15. 15

    Verily I say unto you, a name is a promise made to a stranger who hath not yet been hired. Keep the promise, and thy code shall outlive thee; break it, and the compiler will forgive thee, but the next reader never shall.

The First Gospel of the Circuit, Chapter 49:1–15.