Software Is Written Once And Read For Years Afterwards

The daily work of a programmer is mostly comprehension, not composition. Once you accept that, a great many arguments about craft settle themselves.

Ask a room of working programmers how they spend a day and the honest answers rarely feature long uninterrupted stretches of typing. The day is spent reading. Reading the thing that broke. Reading the part of the system that touches the thing that broke. Reading a change somebody else proposes, trying to hold enough of the surrounding context in your head to say whether it is safe. Reading your own work from a fortnight ago and finding that the person who wrote it left you almost nothing to go on. Typing happens, and it matters, but it is the smaller half of the job by a wide margin. Craft, then, is mostly about what you leave behind for the reader.

This is not a sentimental observation. It has hard consequences for how you decide things. If reading dominates, then a choice that saves you two minutes now and costs a future reader twenty minutes is a bad trade, and it is a bad trade even though you will never see the bill. Compressed logic that you find elegant on the day you write it is a liability if it takes someone else half an hour to reconstruct your reasoning. Clever is not a compliment in this trade. The compliment is obvious, and obvious is much harder to achieve than clever, because it requires you to imagine a reader who does not share your context.

The reader you should imagine is specific. It is not a beginner and it is not a genius. It is a competent practitioner, under time pressure, at eleven at night, holding a pager, looking at this part of the system for the first time. That person does not have your assumptions. They do not know which of the three similar looking paths is the one that actually runs in production. They cannot ask you, because you have moved on or moved out. Everything you can do to shorten that person's path to understanding is craft. Everything that lengthens it, however defensible in the moment, is a cost you have quietly transferred to somebody else.

Four subjects follow from this and they organise most of what we plan to publish. The first is naming and reading: the accuracy of the words you choose, and the difference between a comment that repeats the logic and a comment that records the reason for it. The second is the shape of a change: how big a piece of work should be if it is to be genuinely reviewed rather than nominally approved, and what a message attached to that change ought to say. The third is errors and failure: the vocabulary we lack, and the habit of failing loudly at the edge rather than quietly in the middle. The fourth is inherited code.

That fourth one deserves a word here because it is the least discussed and the most common. Very few practitioners spend their careers on systems they designed. Most of us arrive at something already running, already carrying users, already shaped by decisions whose reasons have been lost. The instinct on arrival is to judge it, and the instinct after judging it is to rewrite it. Both instincts are usually wrong, or at least premature. Code that is ugly and works contains information. It has been shaped by contact with reality, and some of its ugliness is the shape of a real problem you have not met yet.

None of this is a method and we will not be selling one. There is no sequence of steps that produces good software, and anybody who tells you otherwise is selling something with a price attached. What exists instead is a set of habits that practitioners converge on, usually after being burned, and that are much easier to describe than to hold to under pressure. We intend to describe them plainly, in prose, without reference to any particular language or tool, because the habits outlast the tools by a considerable margin. What follows in this issue is a start on that, not a finish.