By Peter Feltham, Solutions Architect

I went to a talk titled ‘Is Code Poetry?’ during the Sydney Writer’s Festival last month. My immediate answer to the titular question was ‘no, of course not’ – in fact it brought back the embarrassment I’d feel when my Dad would suggest filling in ‘Java, C++…’ on forms asking for ‘Languages spoken’. Seriously, programming doesn’t even begin to approach natural language – for a start most programming languages have less than fifty words in their vocabularies and besides, who ‘speaks’ in code anyway?

Well, the talk soon answered that question: there actually is a small movement of writers producing ‘code poems’ and ‘electronic literature’. More interesting to me though was a story told by the second speaker, the Australian futurist and co-inventor of VRML Mark Pesce.

Mark told the story of a time he was hired to do a kind of forensic analysis on the source code of dozens of well-known videogames. The unnamed company that hired him wanted to find instances of graphics algorithms that might infringe patents it had cheaply acquired, so it could prosecute them. Although I’m appalled by the ethics of such a mission, what programmer wouldn’t love to read that code? I’ve read the source code to Quake (its maker, Id software, open-sources its code after five years), and it’s like watching a master at work.

Ghosts of coders past

So Mark spent weeks in isolation reading videogame source code, and in so doing he was absorbing the stories of the programmers who worked on those games. He told us about the three broad types of coders he met through their code.

The first were the kids straight out of school, landed miraculously in their dream job and being ground half to death by its relentless demands. Don’t like it? Well there’s a long line of hopefuls dying to take your place. You don’t have to look hard to find horror stories of young coders who’ve been chewed up and spat out by the big videogame studios.

The next contained those Mark called the ‘Journeymen’. They’d made it through to the other side of the gruelling first years and had developed a workmanlike style, turning out practical, effective if uninspiring code. You could see their battle scars in their practical constructs and their tried-and-true bags of tricks.

The last and rarest were the masters. Reading the source of one game had Mark scratching his head over a seemingly disconnected set of data-like modules, each similar but subtly different, and which seemed meant to fit together in some way but whose overarching purpose eluded him. It wasn’t until he read the final piece that the whole was revealed, a revelation that Mark says gave him the same sensation of beauty and elegance as when a poem’s closing word reveals the meaning of the rest with irreducible succinctness.

The game was Miyamoto’s Mario Kart.

What does your code look like?

Something that has long fascinated me is what makes for good code. There’s an unlimited variety of ways to tackle any programming problem, so what makes some pieces of code better than others? And for that matter what makes some coders better than others?

As I matured as a programmer I learnt a series of lessons that made me a better coder. I learnt that a bit of planning before coding isn’t a waste of time; that writing ‘clever’ code usually isn’t smart; that reusing existing code is almost always better than writing your own; that bugs are inevitable but you can minimise the damage by coding defensively. As I reflected on Mark’s story, I found a common thread that led me to my new coding motto: know your audience.

Programming is communication, but with whom are we communicating when we code? I have a feeling that many programmers instinctively write for the compiler, and I think I started out that way too. But the compiler doesn’t care. Your audience is other programmers.

As Mark’s story shows, code is more than just instructions for a machine; it’s written by people and read by people, it’s subtle and carries implicit information that the compiler doesn’t comprehend. When people read code it’s because they need to understand its meaning, perhaps because they need to fix a bug or add a new feature, integrate it with something else or even incorporate it into something new. If code is well written, it’s easy to understand and work on; if not then it can be a nightmare.

Writing this kind of good code means writing with your audience in mind. It means trying first and foremost to be understood by other people, not just by the compiler.

Coding for humans

Now I can see that the lessons I’ve learnt so far about writing better code all contribute to making code easy to read and understand. I’ve learnt to use patterns and conventions, even if I need to research whether one exists, because they’re easily recognised and they convey my intention implicitly; to choose common code libraries, because my audience probably already knows them; to think hard about what to name my objects; even to never cut corners, because the way I code influences others.

I need to talk about code comments because educators always stress their importance. Good code can explain itself so comments shouldn’t just paraphrase it. I think comments should be used to add context. Code itself can’t tell you when and how it is used, or why it was written that way, or what bug it fixes but comments can. Good comments can even guard against well-meaning attempts by others to ‘improve’ code that was put there for a good reason.

So code may not often be poetry, but it is a form of communication, and therefore (although it’s not the stereotype) good coders are great communicators. My message to my fellow coders is: you might be being crunched by a tight deadline right now, but spare a thought for the next person to read the code you’re writing. It might even end up being you.