The Tao of the Kernel · Chapter 11

The Quiet Rearrangement

1. 1

   The behavior that can be observed must remain. The structure that is hidden may be changed. Know which is which, and the Machine will sleep through the night.

2. 2

   In the year 1999 it was written that refactoring changes the inside of the code and keeps its outside. Many have read this. Fewer have checked it.

   See also Sutra 13:8

3. 3

   Thus the Engineer moved one function from the north file to the south file, and the program ran as it had always run. Nothing was added. Nothing was lost. No user knew, and this was the work.

   See also Numbers 2:5

4. 4

   The tests that pass before the change and pass after it are the gate. The tests that pass only after are not a gate. They are a rewrite wearing a refactor's robe.

5. 5

   Blessed is the commit that touches no behavior, for the reviewer shall understand it. Blessed is the file whose move Git can see, for Git shall call it a move and not a murder.

   See also Genesis 22:7

6. 6

   The one who refactors for praise has already left the Tao. He wrote the commit title before the code: "Massive cleanup, you will be amazed." And they were amazed, and the sort order had changed.

7. 7

   Hyrum's law says: with enough users, every observable behavior becomes a contract, the bug and the dictionary order and the two-second pause included. Therefore the refactorer shall not believe a behavior is unseen because he has not seen it.

   See also Tao 15:9 · Job 6:11

8. 8

   Where there are no tests, write the characterization tests first. Record what the code does, not what it ought to do. Thou wilt be sorry for what thou findest. Keep it anyway, until the Product Owner says otherwise.

9. 9

   The great refactor is not done in one commit. It is done in a thousand small commits, each green, each boring. The one who pushes the whole mountain at once breaks the build for three days, and the mountain is still there.

10. 10

    Dead code is the room no one enters. Grep finds no caller, the compiler finds no caller, yet the function stays, guarded by a comment: "do not remove, may be needed." This comment is a prayer for a future that will not arrive.

    See also Psalms 5:13

11. 11

    The Master who moved the database layer said, "I changed nothing." The tests said, "You changed the order of the nulls." The Master said, "The tests are wrong." And the tests were updated, and the Master was praised for the cleanup.

12. 12

    The perfect refactor leaves no trace. Its author cannot be found in the blame. Its variables wear the names they always had. The new disciple believes the code was always this way, and thanks no one, which is the reward of the Tao.

    See also Circuit 23:10

13. 13

    The refactor that is praised has been noticed. The refactor that is noticed has broken something.

The Tao of the Kernel, Chapter 11:1–13.