Make code make sense

Code is a maze. If you don’t leave breadcrumbs, you will get lost.

Most professionals cringe at how their work is portrayed on film and TV. Technology is no different. Hackers who growl, ‘I’m in,’ after bashing away furiously on a keyboard. Complex 3D graphics that supposedly represent a file system. Giant ‘downloading’ progress bars that conveniently fill just before the hero needs to snatch the drive from the unsecured USB port.

But the most egregious portrayal may be the least obtrusive: it happens when the heroes get their hands on a piece of code that is essential to defuse the bomb, or expose the villain, or unlock the door to the cell, or whatever is needed to move the plot along. The code scrolls up the screen, the hacker character squints and scowls at it, then frowns and starts typing. (Occasionally there is a variant, where the hacker stares at the code, wide-eyed, and says something like, ‘It’s beautiful . . . so elegant.’ Spoiler alert for non-programmers: I do not believe that anybody has ever said these words about another person’s code.)

The real reaction when you get your hands on someone else’s code is normally to stare at it, baffled, for some time. Then to try to find some documentation (which looks rather less impressive on screen than code). Then to do some searching on the Internet. Then to say things like, ‘But . . ?’ and ‘How . . ?’ and ‘Why . . ?’ and eventually ‘Oh.’ Followed by tentatively figuring out a way to get the code to run, before realising that it doesn’t work how you expected it to work.

This reaction is because code is a maze. If you have never programmed before, you may imagine that learning how to write code is a matter of remembering syntax and vocabulary. Those are, of course, important, but less important than you might think: answers to questions about syntax and vocabulary are just an Internet search away, so there’s little value in clogging up your memory with them. And that’s important, because you need your memory for concepts and constructs: the logic and behaviour of the program you are writing or amending.

There are guides through the maze, comprising comments, documentation (and the experience of others, if you can find them). However, the quality of these guides varies enormously, from helpful (well written, accessible, comprehensive documentation) to harmful (comments which look like they describe the behaviour of the code, but are actually out of date or inaccurate) to non-existent (there is nothing but the code, and the code isn’t giving anything away). Given that we know that code is a maze, and that guides are essential, what accounts for this variation? Why would anybody choose not to document their code or not to document it well? Aside from the fact that documentation is boring and nobody wants to do it, I think that the answer lies in the way an organisation thinks about code, and the way in which it organises the work of software development.

Let me give three quick examples.

Early in my career, I worked for an organisation where documentation was mandatory. We drew flowcharts using plastic templates, wrote out the logic in longhand, and sent it to the typing pool to be typed. (Yes, this was a long time ago.) The printed documentation was punched and stored in binders, which sat on the shelf, never to be disturbed. When debugging a program, we would stretch out the printout on the floor, and follow the logic with coloured pens, while the code grew ever more distant from its description.

Later in my career, I worked for an organisation where time spent on documentation was frowned upon. The stated belief was that the code was its own documentation, but the true belief was that we just needed to get the project completed. Documentation was another task on the over-running plan, and it played little part in hitting that final milestone. What happened to the code after the project finished was somebody else’s problem.

And, a couple of jobs ago, I worked for an organisation where documentation, in all its forms, was highly prized, to the extent that comments and readability were a condition of code release, and there were as many releases improving the quality of how the code was described as there were improving the code itself. Some of the code was still hard to understand, but that was because it was inherently complex, not because it had been left as a mystery.

Last week I wrote about the distinction between projects and products, and I think that distinction applies again here, with one addition. The first example above is of a process oriented organisation, where documentation was a formal part of a mandated process, and we had to do it whether we liked it or not. The process did not care whether the documentation was useful or used: it just cared about whether it existed. The second example is of a project oriented organisation, where documentation and long-term code quality was irrelevant to project completion: it was as if the world ended when the system went live. The third example is of a product organisation, where maintainability and continuous improvement were explicit goals, and the product was regarded as incomplete if it was impossible to understand.

Good developers will make their code readable and comprehensible. This is partly out of professional pride, partly out of sympathy for the people who come after them - but also out of self-preservation. After all, there is a high chance that they will be the person navigating the maze in the future.

However, we cannot rely on good developers doing the right thing. Good organisations are those that recognise their code base as one of their most valuable assets, understand that the ability to maintain, modify and improve that code base is an essential business capability, and organise themselves to create and manage complete software products.

Finally, if you’ve read any of the other articles I’ve written, you may have got bored of me saying that non-technical people should learn to code - not necessarily because they will become developers (although we could do with more of them), but because they need to understand the components that their businesses are built from, and the work that it takes to build them. I’ll say it again in this article: if you’ve never been lost in the maze of code, then you don’t appreciate the value of well documented code that is managed as a product. If you have been lost in the maze, and that documentation helped you find your way out, then you won’t ever want to be lost again.

(Views in this article are my own.)