The Tao of the Kernel · Chapter 13

The Tao of the Self-Documenting Code

1
There is a code that documents itself. It needs no comment, and so it leaves none for the one who comes after.
2
The comment that reads "increment the counter" describes the road the reader already walks, and not the reason the road was built.
3
The comment that was true when it was written is a lie told kindly. The compiler does not read prose, so it never notices the lie.
4
In the year 1984 the Prophet Knuth taught that programs should be written as literature for human minds. The Machine read only the code, and was content.
5
The README answers every question its author once had. The author has since forgotten the questions.
6
What is written for the writer is read by no one. What is written for the reader is read by the writer, six months later, in a language the writer no longer speaks.
7
The function named process processes. The variable named tmp2 holds what it holds. Both are clear to the one who made them, and both are silent to the rest of creation.
8
The one who documents every function has a wiki that no one opens. The one who documents nothing has a wiki that does not exist. The two keep the same silence.
9
The setup guide begins: first, install the dependencies. It does not say which, nor which version, for these were obvious to the one who knew them, and he has since gone to work elsewhere.
10
The docstring said: Returns the value. The function returned the value. Thus two things agreed, and said nothing at all.
11
The commit message said: fix. The diff showed what changed. Neither could say why, and git blame points only at a name, which is not an answer.
12
Blessed is the one who writes the why, for the what is in the code, and the code is patient and will wait forever.
13
Hear now the last teaching: he who writes for himself writes for a stranger who will not return. Write for the stranger, for the stranger is thyself after the coffee wears off, and thou wilt not remember what thou knewest.
See also Leviticus 9:12 · Preacher 3:12

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