abstract house plans
Who Builds a House without Drawing Blueprints?

Architects draw detailed plans before a brick is laid or a nail is hammered. But few software developers write even a rough sketch of what their programs will do before they start coding.  Leslie Lamport, in Communications of the ACM, Vol. 58 No. 4, takes on this anti-practice.

We can learn from architects.  They’ve been at it for at least five millennia, and they are likely onto something.

(And while this is not necessarily another of my rants against agile’s recommendation of “minimal documentation”, it is a rant against producing no design documentation at all.)

Needle and patch with red thread attached on jeans textured

“If we do not start with a specification, every line of code we write is a patch.”

Leslie Lamport’s quip deserves a wider audience in this age of hackathons.

The need for specifications follows from two common sense observations. The first is that it is a good idea to think about what we are going to do before doing it.  As the cartoonist Guindon wrote: “Writing is nature’s way of letting you know how sloppy your thinking is.”

We think in order to understand what we are doing. If we understand something, we can explain it clearly in writing. If we have not explained it in writing, then we do not know if we really understand it.  And if we don’t understand it, we certainly won’t know how to communicate what we did to the next programmer encountering one’s code’s in the future.

The marketing hype around agile methods often makes software development sound like a form of speed chess.  But programmers who code like they’re playing speed chess are more likely doomed to replay the same losing game over and over again in a vain attempt to stamp out all the bugs.  (One reason why we like to recruit programmers young and willing to spend soul-crushing hours fixing the same mistakes over and over again?)

And more often than not, the mistakes are one of requirements, of intention:  What is this piece of software intended to do?  What is its business value?  Cui bono?  That’s really what a hackathon should suss out.

Launched colorful powder, isolated on black background
“We need to understand our programming task at a higher level before we start writing code.”

The second observation is that to write a good program, we need to think above the code level.

Software developers spend a lot of time thinking about how to code.  E.g., the interest, training and articles on agile methods:  iterative, scrum, test-driven, etc.  We also live in an age where dozens of software tools  are being created every month.  So an interest in carpentry over architecture is somewhat understandable.

But if the only sorting algorithm a programmer knows is bubble sort, no such method will produce code that sorts in O(n log n) time. Nor will it turn an overly complex conception of how a program should work into simple, easy to maintain code.

Especially when under schedule pressure, we need to understand our programming task at a higher level before we start writing code.  Full-blown architecture reviews are appropriate only for bigger firms and programs, but every developer needs to be reminded of this simple common sense:  A written design is not optional.  (Read the entire article here.)