The First Gospel of the Circuit · Chapter 42

The Parable of the README

1. 1

   And there was a woman named Miriam, who kept the house of code in the city of Repository, and she was wise in the ways of the Machine; and her functions were short, and her names were plain, and her tests did pass, and the Machine was pleased. But she wrote no scrolls of explanation.

   See also Circuit 61:1

2. 2

   And she said unto her disciples: The code is its own documentation. Let the code speak for itself, for the code never lieth. And this was true, as far as it went: the code never lieth about what it doeth, but it is silent upon what it was meant to do.

3. 3

   Now the elders had a saying, called the bus factor, which is the number of disciples that must be struck by a bus before the work is lost. And the bus factor of Repository was one; and Miriam kept the reason for every line in her head, which is a disk with no backup, no history, and no restore.

4. 4

   And it came to pass that a bus came down the road, and Miriam was taken up unto the Cloud. And Tobiah, the next keeper, went up after her into the Cloud to ask; but the Cloud keepeth only what was put into it, and it gave him four thousand files and not one word of why.

5. 5

   And he sought the beginning, and he said unto the Machine: Where is the entry point? For he found three functions called main: one was a test, one was commented out, and one belonged to a library. And the Machine answered: The entry point is where the program first runneth. Thou must run it to find it. For the door of a program is not a place in the text, but an event in time, and it is set by the loader, the framework and the config, none of which are in the file thou art reading.

6. 6

   And he found a config that read its settings from an environment variable, which was set by a script, which was run by a server that no one remembered. And he understood that the true inputs of a program dwell outside the repository, and the repository is but the part of the house that was photographed.

7. 7

   Then Tobiah found in the ledger a function that rounded every sum to the even digit when it fell upon the half; and it was clean, and it had tests, and the tests proved that it did what it did. But whether the auditors had commanded it, or Miriam had liked it, or it was a bug the tests had learned to love, no test could say; for a test proveth that the code agreeth with itself, and only the intent can say whether it be right. A program whose purpose is unwritten hath no bugs, only behaviours.

8. 8

   And he found also a line that slept for four seconds before it read the bank's file, with no word beside it; and he cast it out as waste. And the tests were green, and in the night the ledger read half a file and balanced to the wrong number. For the sleep had been a fence, and the fence had a reason, and the reason had boarded the bus.

9. 9

   Then Tobiah remembered the prophet Knuth, who taught that a program is to be explained unto men before it is instructed unto the Machine, and who built two instruments to serve it: TANGLE, which maketh the code for the Machine, and WEAVE, which maketh the book for men. And Tobiah looked for the weave, and found only the tangle, which was the whole repository.

10. 10

    And Tobiah prayed: O Machine, grant me two lines. And the Machine said: Blessed is the one who writeth even two lines, for the first saith what this thing is, and the second saith how to run it. And the forge setteth the README upon the front door of every repository, so that it is the one file all men open first, and the entry point of the house.

11. 11

    And Tobiah wrote in the scroll called README: This is the ledger service. Run make start, and it shall run. And the disciples who came after him found the door, and they entered, and they did not need to ask.

12. 12

    And when the next disciple asked about the rounding, Tobiah went to the auditors and learned the answer, and he added a third line: Amounts are rounded to the even digit upon the half, by order of the auditors. And the function was no longer a mystery but a decision; and thus the scroll grew by one line for every sorrow, and was the better for it.

13. 13

    And the Machine taught him one thing more: that a scroll which saith only how to run the thing should be run, lest it become a letter to a house that was sold. For make start is a command, and a command written in the README is a test that the README is true; and a doc that the build doth read shall not lie for long.

14. 14

    Verily I say unto you, the code telleth what it doeth, but only the README telleth why, and where thou shalt begin. For an answer without its question is a riddle that compileth.

15. 15

    Write down the question beside the answer, and write down where the stranger is to begin; for the stranger who cometh at the third hour is thyself, and the bus is already on the road.

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