The Long Read

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.

Naming And Reading

A Good Name Removes The Need For A Comment

When you find yourself explaining what something is, check whether the name could have said it instead.

The Particular Damage Done By A Name That Is Nearly Right

An obviously wrong name gets corrected. A slightly wrong one gets believed.

Comments Should Explain Why, Because The Code Already Says What

The reasoning behind a decision cannot be recovered by reading the decision.

The Shape Of A Change

Small Changes Can Be Reviewed And Small Changes Can Be Reverted

Size is not a stylistic preference. It determines whether the safety mechanisms work at all.

A Large Change Is Hard To Judge So It Gets Approved Unread

Beyond a certain size, review stops being an inspection and becomes a formality.

Write The Message For Whoever Investigates The Fault Next Year

The audience for a change message is not your colleague today. It is a stranger tracing a problem backwards.

Errors And Failure

Three Words We Use Interchangeably And Should Not

A fault, an error and a failure are different things, and confusing them muddles every incident discussion.

Fail Loudly At The Boundary Rather Than Quietly In The Middle

The best place to detect wrongness is where it enters, not where it eventually causes damage.

Most Incidents Come From A Case Somebody Decided Could Not Happen

The impossible branch is not rare in production. It is where production spends a surprising amount of its time.

The Code You Inherit

Reading An Unfamiliar System Without Trying To Hold All Of It

You cannot understand a large system at once, and attempting it is the slowest possible start.

Resisting The Rewrite Until You Understand What It Is For

The urge to replace an inherited system is strongest at the moment you know least about it.

Pin The Current Behaviour Before You Change Any Of It

Tests written to describe what a system does today are the only safe footing for changing it tomorrow.

About G8 Softwares

G8 Softwares is about the craft of writing software, written for the people who write it. Not the business case for building something, not the architecture of large systems, not the tooling that surrounds the work: the work itself, at the scale of a name, a change, a boundary, a file you did not write and now have to modify. We take the view that this scale is where most of the difficulty actually sits, that it is discussed less than it deserves because it is unglamorous, and that the habits which help are stable enough to be worth writing down carefully rather than restating as slogans.

We write in prose and we avoid naming languages, tools and products, which is a deliberate constraint rather than a stylistic quirk. The reason a nearly accurate name is dangerous does not depend on syntax. Neither does the dynamic by which a very large change receives less real scrutiny than a small one, nor the pattern where an outage traces back to a condition somebody reasonably decided could not occur. These things recur across every environment we have seen, and describing them without the particulars keeps the writing useful to a reader whose daily circumstances are nothing like ours. The specifics change every few years. The difficulties do not.

There is no methodology on offer here and no claim that following any of this guarantees an outcome. Software is written by people under time pressure with incomplete information, and any account that leaves out the pressure and the incompleteness is describing something other than the job. What we can do is set out the trade honestly: what a practice costs, what it buys, and when it is reasonable to decide against it. Readers are assumed to be competent and busy, capable of disagreeing, and better placed than we are to judge their own circumstances. That assumption shapes everything published under this title.