Writing by Peter Hilton

Neil Gaiman’s rules for coding

@neilhimself writes about programming 2014-08-20 #programming

The problem with getting programming advice from programmers is none of them are really famous, and hardly any of them can write. It’s easier to get good programming advice from someone a famous novellist.

George Orwell is not the only writer to give advice to programmers. The Guardian’s collection of Ten rules for writing fiction, includes a contribution from Neil Gaiman, who is also somewhat famous (two million Twitter followers at the time of writing).

Gaiman’s eight rules cover several areas of software development, although he uses the word ‘writing’ when he means ‘coding’. These rules require little comment.

Productivity & agile software development

  1. Write.
  2. Put one word after another. Find the right word, put it down.
  3. Finish what you’re writing. Whatever you have to do to finish it, finish it.

Gaiman starts by emphasising that coding requires practice and deliberate creative effort, while not losing sight of the big picture. Both getting things done (rules 1-2) and working software in production (rule 3) are important.

Code review

  1. Put it aside. Read it pretending you’ve never read it before. Show it to friends whose opinion you respect and who like the kind of thing that this is.
  2. Remember: when people tell you something’s wrong or doesn’t work for them, they are almost always right. When they tell you exactly what they think is wrong and how to fix it, they are almost always wrong.

Rule 4 advocates thorough code review, and rule 5 is a warning to respond thoughtfully to review comments from other team members, while still taking responsibility for the quality of the code you commit.


  1. Fix it. Remember that, sooner or later, before it ever reaches perfection, you will have to let it go and move on and start to write the next thing. Perfection is like chasing the horizon. Keep moving.

Rule 6 is clearly about technical debt: in a homage to The Joel Test (item 5 - fix bugs before writing new code), Gaiman advocates addressing technical debt early. However, this is balanced by a clear reference to Scrum: software improvements must have business value, and it is essential to prioritise all work.

Code comments

  1. Laugh at your own jokes.

Gaiman is certainly unconventional: not only does he advocate actually writing code comments, but he also recommends the use of humour in comments. This technique, which can also be successful in technical documentation, encourages programmers to retain their humanity and have fun despite the horror of legacy code. Crucially, jokes in comments aren’t only for other team members: the idea is that you find them funny yourself too.

Open-source software

  1. The main rule of writing is that if you do it with enough assurance and confidence, you’re allowed to do whatever you like. (That may be a rule for life as well as for writing. But it’s definitely true for writing.)

In this last rule, Gaiman offers his support to open-source software, with this final rule that encourages programmers to follow their own vision to write whatever code they think needs writing. He continues:

So write your story as it needs to be written. Write it honestly, and tell it as best you can.

This is another homage, this time a salute to Eric Raymond’s lesson that:

Every good work of software starts by scratching a developer’s personal itch.

Finally, the last word goes to Gaiman:

I’m not sure that there are any other rules. Not ones that matter.

Photo: Ran Yaniv Hartstein

Share on TwitterShare on LinkedIn