Before you write a line of code, you should be able to describe what it does on paper. Not in your head. Not in a hallway conversation. On paper. In sentences. With diagrams if you need them. If you cannot do this, you do not know what you are building. You are typing until something works.
This is not a controversial position. It was not controversial in 1985. It was not controversial in 1995. It became controversial around the time someone decided that "responding to change over following a plan" meant you could skip the plan entirely. Ribbit.
These are two different activities. One is thinking. The other is typing. They require different parts of your brain, different tools, and different review processes. When you collapse them into a single activity called "sprinting," you lose the ability to distinguish between a design problem and a coding problem. Every bug becomes a code fix. Every misunderstanding becomes a refactor. The system rots from the inside because nobody ever stopped to ask whether the thing they were building was the right thing to build.
A functional specification is not a suggestion. It is a contract between the person who understands the problem and the person who knows how to solve it. When those are the same person — and in modern software they often are — the contract is still necessary, because you are not the same person at 10am on Tuesday that you will be at 3pm on Friday. Write it down so future-you can disagree with past-you in a structured way, not by reading the git blame.
My first real system was built from a 200-page functional specification. It was written by a man named Derek who had been in the industry since the 1970s and had opinions about everything. The spec covered every screen, every field, every validation rule, every error message, every report, every batch job, and every failure mode the authors could imagine. It took six months to write. It was reviewed by three people who were not the authors. It had a version number on the cover page and a change log that ran to four pages.
The system ran for twelve years without a major incident. Twelve years. It was replaced not because it broke, but because the hardware it ran on was declared obsolete. The replacement project — led by a team that believed in "rapid delivery" — took eighteen months and produced a system that had its first production incident in week two.
I am not making this up. I am not nostalgic for COBOL. I am nostalgic for the discipline that produced a document so thorough that the code was almost incidental. The code was the easy part. The spec was the work.
Mrs Froggy and I have this argument at dinner. She says that specifications create rigidity. That they assume the world does not change between the writing and the delivery. That the whole point of agile is to accept that you will learn things as you go.
She is not wrong. The world does change. You do learn things. But the response to that is not to stop specifying. It is to specify in smaller batches, review more frequently, and update the document when the understanding changes. The response is not to throw away the map because the terrain shifts. The response is to draw a new map.
A project without a spec is not adaptive. It is adrift. You cannot tell whether you are responding to change or wandering off course unless you have a course to begin with. The spec is the course. If you never wrote one, you are not agile. You are lost.
"If you cannot describe what you are building, you cannot build it. If you can describe it, you can build it twice — once on paper, once in code. The first one is cheaper to change."
At Rib IT Ltd, every engagement starts with a specification phase. The client pays for a document before they pay for a system. Some clients push back. They want to see code. They want a prototype. They want to "move fast."
We explain that the document is the software. The code is a translation. If the translation is wrong, we fix the translation. If the specification is wrong, we fix the specification — and then the translation follows. You cannot fix a bad translation by translating again. You fix it by understanding what was meant in the first place.
This is not slow. It is fast in the only dimension that matters: time-to-correctness. A system built from a good spec works the first time. A system built without one works eventually, after enough cycles of "ship, break, fix, ship again" that nobody remembers what the original goal was.
We have forgotten how to specify. We treat requirements gathering as a checkbox — a meeting we endure before the real work begins. We write user stories on index cards and call it analysis. We confuse velocity with progress and mistaking typing for thinking.
We should not have forgotten. The discipline of specification is what separates engineering from tinkering. A plumber does not start cutting pipes without a diagram. An architect does not pour foundations without a plan. But a software team will happily start coding based on a Slack message and a shared sense of optimism.
The specification is the software. The code is just the final draft. Treat it that way, and your systems will live longer than your hardware. Ignore it, and you will spend the next twelve years wondering why everything breaks.
Ribbit.