Book Club episode II: Wool and the art of software documentation

“Software and cathedrals are much the same – first we build them, then we pray.”Sam Redwine, 4th International Software Process Workshop, 1988

Occasionally, but just occasionally, you end up reading a book that is so good that you can’t stop talking about it to all of your friends. It weaves a story of such magnificence that you’re on the verge of stopping perfect strangers in the street in order to check if they’ve had the pleasure yet. Wool, by Hugh Howey is one of these books.

Honestly, my pictures just get worse and worse. Here's a snake who looks so good out of one eye, but pretty skeletal out of the other. I wonder why. But I've said too much already, etc.

Honestly, my pictures just get worse and worse. Here’s a snake who looks good out of one eye, but pretty skeletal out of the other. I wonder why. But “I’ve said too much already”, etc.

I finally caved during the summer of 2012 to bring a welcome halt to the non-stop nagging I’d been receiving from a friend. I’ll just say this: of all the books I’ve ever been talked into reading, Wool is – by a Norfolk country mile – the best call and I’ve been talked into some crackers. Almost every nook and cranny of the Internet has something about Wool these days, but in the highly unlikely event that you’ve not heard of it or have not had the pleasure yet, you should do so. You’ll not regret it. But let me jump ahead of myself briefly: my friend introduced it as “It’s set in future. People living underground. Lots of strict rules. One in, one out. But I’ve said too much already.” And I tell you, if there’s one phrase that you hear a lot from people trying to talk you into reading Wool, it’s “I’ve said too much already”. Of course, once you’ve read it, you’ll understand just how right this is: don’t do too much research because you seriously don’t want this story spoiled. Resist the temptation. Don’t let your curiosity tarnish something really, really special: incredible depth that just keeps on giving, page after page.

Lots of books, including bloody amazing ones like last time’s book club star, the Pillars of the Earth, reveal their setting’s overall scope at the outset. Very early on, sometimes even from the back of the book alone, you know the entire theatre in which the story will take place. The plot, of course, winds, twists and turns but massive surprise revealings that transform the story’s universe don’t happen. Wool, though, well, words are, as you’ve probably noticed, failing me. It is a book of nested Doctor Who TARDISs that you simply don’t see coming even when you think you do. Take the first half of the opening sentence: “The children were playing while Holston climbed to his death”. This practically grabs you by the balls and begs you to turn the page. Why did he die? Was it an accident? Is he about to be murdered? Who did it? Does he know it is coming? Tell me! TELL ME! Wool positively infects you with curiosity. The words vanish silently into pages as they magically turn in front of you and the story expands in ways you could not have imagined.

Wool: achieving unputdownable status without the need to resort to new branches of physics. Picture credit, XXX

Wool: achieving unputdownable status without the need to resort to new branches of physics. Picture credit, The Great Architect, b3ta

Every time I thought I had figured out what was going on, I was wrong, and some other delightfully unexpected part to the story unfolded. As each delicious piece exposes itself you’re so involved that you barely get a moment to marvel at just how neatly it all fits together. I don’t know how much of the story Hugh had figured out when he set off with that initial small seed of Wool but if it falls anywhere near ‘not that much of it’ then he has achieved what story writers across the globe have consistently failed to do: layer a forest onto a seed without breaking either. Hugh, in the unlikely event that you ever read my “review” I will happily buy a hat just to take it off to you and send you a picture to prove it. Hell, you can even choose the hat.

If you are a fan of science fiction or simply love stories of great depth that explode gorgeously in unpredictable ways then your life is not complete unless you have read Wool: but, again, heed this one teensy smidge of advice – it is very important you know nothing more than the back cover and frankly, not even that (Random House’s 2013 print says too much, in my opinion, so if you buy it, treat the back cover as though it was the final page – a secret from yourself). You’ll feel richer having read it. If nothing else it will reinforce any suspicions that you may have that IT departments rule the world.

But I’ve said too much already.

Code beautiful: segue warning

Since I’m trying to win this year’s “shit segue” award, I figured I’d try and link this into software development somehow. With my recent post on dishwashers “seamlessly” transitioning into a rant on user-interfaces, I thought I had the award secured – albeit by the skin of my teeth – but this one is a sure winner and shows my awesome potential as a DJ. Wool is a special breed of book: it reads by magic. Your eyes look at pages full of words, but that’s not what you see. What you see is pictures, people, emotions. You’re there. The words somehow lift off the paper and end up forming video in your mind. This makes it an effortless exercise in enjoyment: you’re free to sit back and watch a movie, effectively, whilst holding an actual book with pages that simply reads itself. Few authors can do this and Hugh, to the incredible joy of his bank manager, I’m sure, is clearly one of them.

I knew Wool was special when I read it, but I knew it was really special when one day, Mrs Cobras said “can we go upstairs early and read?”. Way-hey! I thought, clothes falling from my body as I rushed upstairs to the bedroom. Imagine the disappointment when it turns out that this actually meant “can we go upstairs early and read?”. Thus, should I ever meet Hugh Howey, as well as taking my hat off to him, I will buy him a beer, but I specifically won’t enjoy doing it. I just feel I ought to. In a Ned Flanders “good host” sort of way.

Given that this was the first book of the many that I’ve tried to palm off on her that she’s actually read, this represents a major gold star for Wool. She picked every single moment that she could to read a page or two and was utterly hooked. Between that and another friend who sent me three texts (and two e-mails) to say how wonderful Wool was – to make sure I knew that the recommendation was appreciated – it’s clear that like rocking horse shit, clean modern trains in the UK, unicorn horns and good customer service from British Telecom, Wool is not something that you find lying around often.

But Hugh isn’t paying me to kiss his arse, so how does this link into software?

Love is shown in the details

The difference between good and great is the detail. Of course, that can pretty much be said about any place on the scale: the difference between outstandingly shite and vaguely bearable is also in the attention to detail shown. Take these two recent examples from Cambridge railway station:

This oozes lack of quality

I don’t know where to begin. I could make a gallery out of these things. Often, trains consist of “8 coa” and are going to “King” and have first class carriages in “carriage 1 &”. For it to be this way for over a year is amazing. This is because it was probably done by the lowest bidder who maximised their profit margins by doing a half arsed job. I’m sure the irony of this is missed on Greater Anglia because they couldn’t care less1.

The lack of detail and attention to quality is of course amazing at first glance until you realise that this is the British Railway system. I am sure that the likes of ATOC, the official turd polishers of the train operating companies, would explain how I am totally wrong in the conclusions that I am drawing here, but humour me anyway. Firstly, these screens are simply not designed to prioritise critical information. If you are in a hurry, often you have to wait for bloody ages to see the piece of information that you require. Secondly, they are poorly laid out: too much detail where there should not be detail and it enough detail where there needs to be detail. Finally, and most unforgivingly, the people who wrote the software did such a fucking piss-poor job that it does not even match the width of the screen. Everything that is important about the special notice is not shown. This is the case with all the data on this screen. And, it has been this way for over a year, thus showing the spectacular lack of pride that everyone involved has in the “service” that they provide. Mere words could not convey how much joy the virtual elimination of commuting has delivered to my life: I died a little bit inside each day I have to give those bum-stands any of my money2.

One of the many things that really, really steams my mirrors is a lack of attention to detail. It shows a messy, untidy mind and just stinks of lack of quality. It also has the mild smell of being done by someone who simply doesn’t care and has no pride in the final delivery. Having worked in software for the best part of a quarter of a century I have had enough opportunities to see such rubbish to write a book on the subject of poorly written code (to be fair, if I step off my moral high-ground briefly, I perpetrated some of that code in my early career). However, each and every page written would raise my blood pressure and I would be dead before I had drafted the first chapter. Instead, I shall bitch and moan in this brief blog post and then go straight to the wine rack and calm myself with a nice castle nine popes3.

Perhaps I just have impossibly high standards or maybe I have been burnt too often to keep making the same mistakes, but I feel that software is not just for Christmas, it is for life. We live in a disposable society and whilst there are signs of that changing, software seems to have taken very well to “knocking it out and throwing it away” as an actual, genuine process: particularly in the games industry. Sometimes the blame can be portioned off the twin evils of software development Mr Schedule and Mrs Specification. Other times, inappropriate process has to step up to the plate: either too much of it, the wrong type of it or–more often than should be the case–absolutely no process at all. Sometimes there is even a soupçon of misused agile around to provide a complete loss of big picture (but by jingo aren’t we cracking through a checklist!). The mistake that many programmers make is to believe that the pie of blame has been fully eaten at this point whereas, in fact, a good half of it is still remaining and that half is theirs to savour and enjoy.

The myth of self-documenting code

“You know you’re brilliant, but maybe you’d like to understand what you did 2 weeks from now.”Linus Torvalds, Linux coding style documentation, 1995

Self-documenting code is something that most programmers claim to believe in but few actually do. Many programmers cannot understand their own code just days after they wrote it but still talk about the importance of self-documenting code. Others simply believe that they are doing it and use that as a justification for writing no comments. I believe this: software is a story and you had better tell a good one that you and others can follow or you might as well have eaten a large bowl of alphabetti spaghetti and shat the results into your computer.

If you can’t tell a good story using an appropriate combination of neat code and relevant commentary then the chances are you have written bad code on three fronts: 1) you don’t care enough to make it nice 2) you have not thought it through or designed it properly and 3) there’s probably no good story to tell. And that’s selfish. This means that one day, and possibly one day soon, some other programmer will come across this code, realise that it is awful and be forced to rewrite it and on too many occasions in the first decade of the new millennium, that other programmer was me. If the people paying the programmer are fortunate enough, that person won’t replace one chunk of bloody awful code with another bloody awful chunk of code.

Self-documenting code without suitable commentary is largely a myth. Raw source-code doesn’t contain editorial, thoughts, considerations: it doesn’t explain the why. What was the programmer thinking? When was this done? Why is the algorithm done in this way and not that way? Was it because of a standard library problem? What were the ideas at the time for improving it? Why was this corner cut? This stuff is important and no programmer should have to spend days in source-control trawling the history to figure out basic context. It infuriates me that programmers don’t feel the need to tell a story that they and others can reconstitute with ease down the line: one where the purpose of the code leaps out at the reader along with all the interesting footnotes and commentary that provide context and encourage a relationship between the writer and reader. Remember: one day you could be that reader.

Software life-spans demand exposure of intention

The year 2038 problem
32 bit Unix systems, and they are plentiful across the globe in everything from power stations though ticket machines, trains and appliances, represent the date as “seconds since 00:00, January 1st, 1970.” in a signed 32 bit integer. This means that the maximum number of seconds it can store is 232, which translates to 3:14.07AM, Tuesday 19th January 2038. One second after that, it will roll over to zero. Any code that uses “greater than” or “less than” on a time value at that point will stop producing correct results. And if you’re in any doubt that today’s computers will be in operation in the year 2038, think very carefully when you’re on a train built in 1975 or powered by a power station built in the 50s, 60s or 70s.

Code without comments shows function, but not intention. That’s something you’ll appreciate if you’ve ever waded through code that has fantastic layout, amazing, readable variable names, cracking function names but is still frustratingly challenging to figure out enough of the “what” and “why” just so you can make one, small modification that would’ve taken five minutes if the original author had just had the decency to slap a couple of lines of text in describing the code’s intention. Of course, one could always write a specification or some separate documentation, but out of la-la land and back in reality we all know that isn’t going to fly. Separate documentation is rarely finished, rarely updated and usually lost. It’s a waste of time for everyone and good programmers rarely have the time, patience or ability to create wonderful documents. Documentation should go where it is useful to those who need it, which means in and amongst the code itself. It’s easy to update, it tells the right story and oozes context where context is needed.

Software’s life-span has an annoying habit of being considerably longer than anticipated which is why there was a Y2K problem in the first place and why there will be a year 2038 problem twenty-five years from now. And that’s forgetting the short-term pain caused by warming the cockles of managers by ticking boxes early in a project with a “we’ll fix it later” attitude that helps explain why the last 10% of so many projects takes 90% of the time: it is in fact 90% of the work and everything up until then has been a barely functioning skeleton of badly documented, poorly structured temporary code interleaved with special cases that just meets the requirements for leaping from one milestone to the next. One could call this “house of cards” development and it leads to more wasted time (and therefore money) rewriting unintelligible code than anyone can possibly imagine.

Everyone has their excuse for banging out disposable hieroglyphics instead of readable software, but my favourite three are “it’s self-evident what’s going on, it’s self-documenting” (hahahahaha!), “I’m in a hurry, I’ll come back and comment it later” (you won’t) or “yeah, but then I’ll have to update the comments every time I update the code” (demonstrating a phenomenal lack of understanding of the very basics of creating narrative). No matter how you wrap ‘em up, though, they are excuses; either ways of disguising bad code through obfuscation of shiteness or rendering good code bloody useless by requiring readers to engage in hours of close examination to find out what’s happening. If it is a beautiful algorithm written with pride then it deserves to be presented as such for all to appreciate for years to come.

Bad programming is just natural selection at work

“Debugging is twice as hard as writing the code in the first place. Therefore, if you write the code as cleverly as possible, you are, by definition, not smart enough to debug it.”Brian Kernighan, explaining elegantly that readability and structure trump being a smart-arse

Of course, the light at the end of the tunnel isn’t always the train coming the other way. Even in the games industry, the onlineification of software is increasing life-spans of code to the point that good, careful design is beginning to become an essential part of the arsenal of weaponry required to stop programmers killing each other as well as ensuring that one doesn’t attempt the futile task of building fifty story tower-blocks on foundations designed for a garden shed. Long-term survival is increasingly dependent on stamping out a fire-and-forget attitude that came from slapping it into a box and shipping the damn thing which up until recently was pretty much where each game’s software story ended (“What? No class-A bugs you say? Ok – everyone step away from their computers. We’re shipping.”).


Code should be beautiful. Your source should be a work of art. The story you are telling should leap from the page out to all the programmers who see it. Maintenance work should be trivial to do: you know the old saying, write your code as though the person who will maintain it is a dangerous psychopath with a desk drawer full of loaded guns.

Make your code read like Wool does. Like a good book, the story should lift effortlessly into the eyes and minds of the readers, because it shows that you care. It shows you’re a good programmer who believes that the quality of what’s under the hood is directly related to the quality of the deliverable.

1 Please take note, those of you who get this wrong (I’m looking at you, large portions of the USA), it’s couldn’t care less, not could care less. The meaning is completely different and when you use the latter you’re not saying what you think that you’re saying.
2 But I’m not bitter. No, wait, that’s not right, I am bitter.
3 Don’t worry, I know.

This entry was posted in Software development and tagged , , , , , . Bookmark the permalink.

3 Responses to Book Club episode II: Wool and the art of software documentation

  1. Dave says:

    Self-modifying code neatly obviates the need for documentation. It’s what Turing would have wanted.

  2. Montaigne says:

    5 months without a post? What’s going on?

    I read Wool at your suggestion, several months ago. It’s awesome. I very much look forward to the sequels which are due out at some point.

    Life must be perfect for you right now if there is no requirement for rants :)

    • Chief Cobra says:

      I know, I know… I’ve got my usual excuses. Worst thing is, that I actually have several drafts together, most of which are not rants. How’s that for a miracle? I’ll try and get a couple of ‘em out for Christmas :)

Leave a Reply