Write Like A Programmer

I program computers and I also write. There is more than one way to program, but there are a few good practices in programming which have analogous good practices in writing. Here is how you write like a programmer.

The following is not necessarily advice.

 

First, write with purpose. Do not write just because. Don't write because you love writing, because you love reading your own writing, because you love other people reading your writing or because you love feedback. Instead, write because you have an objective. Your text is supposed to achieve something. Write because you want your writing to accomplish something, because you want your writing to have an effect on the reader.

In fact, flip those two things around in the phrase, in order to make the emphasis clearer: First, develop an objective. Discover that there is a story you want to tell, a particular piece of information you need to share, an emotional instant that you want others to experience, a particular reference work missing from the world. Second, in order to accomplish that objective, write.

 

Write a first draft. Get it out in front of you, in a basic form. Then start thinking. What are you trying to achieve? How does the thing in front of you achieve this, or doesn't it? How does it need to be modified to better achieve this goal? It's easier to edit from a thing to a better thing than it is to build on blank space, a winking cursor in an empty text editor.

Planning is fine in principle. It can save you time in the long run, if the thing you're writing is large. But you cannot work everything out before you start. It is possible to spend your entire life hypothesising about what words you will use when you eventually write the thing, and never write the thing. A time comes when you must get your hands dirty, and physically touch a keyboard. Once you start writing for real, you may discover important facts which mean all your planning was pointless. This is undesirable, but also unavoidable. The only solution is to get started.

 

Then, edit. Refactor your text. Just because you've reached the end doesn't mean you're done. The first thing that it occurred to you to write was almost certainly not the best thing to write. Re-read the text, and be critical. Put yourself in the mindset of a critic, actively searching for faults or weakness. Stay focused on your objective, and remember that every line of your text must serve this objective. Keeping this purpose in mind makes it easier to be dispassionate and pragmatic.

Be organised. Divide your major objective into smaller ones and use chapters or section breaks to address these individually. You can go to an extra level of granularity with individual paragraphs. Group statements into paragraphs according to purpose and subject matter. Make them self-contained. Try not to refer to topics or terms before they have been adequately introduced.

State exactly what you mean, and try to avoid ambiguity or misunderstanding. Don't ramble. Don't let sentences get too long. Don't try to convey too many different thoughts in a single sentence. Break things down into simple terms. "Simple" does not necessarily mean "obvious". Simple terms can take quite a bit of thought to come up with. Sometimes it can be obvious that there is a simple term, but not obvious what it is. Avoid idioms.

In general, choose your words carefully. Word choice error is normal and unavoidable. A word which made perfect sense at the time you wrote it can be obviously wrong once you come back to it later, with the entire rest of the document clearly in your mind.

 

And be brief. In fact, be merciless. Murder your darlings once they cease to be useful. Yes, that paragraph is beautiful, you slaved away on it - but it no longer serves a needed purpose, so scrap it. It's okay: there are limitless more words in you, where those came from. You are not a dumber person now that you've written them, or now that you've deleted them; you are capable of equally excellent paragraphs, still.

Remove unnecessary words and statements. However, do not misunderstand the meaning of the word "unnecessary" here. An unnecessary word is one which does not serve your objective. However, just because a word or statement can be removed, and left implicit, doesn't mean it should be. Clarity can serve your objective. Brevity is good, but clarity is better. Brevity is good for keeping a reader's attention, delivering a good density of information and/or action. It means the reader's time is not being wasted. However, too much brevity becomes obfuscation. Without clarity, a reader reaches a point where they just can't keep reading at all because they can't understand what you're saying. Sometimes, repeating yourself for clarity is appropriate.

 

With clarity in mind: Punctuate correctly, capitalise correctly, format consistently, and check your spelling. Minor errors of this nature are not fatal, but they slow the reader down. They can mount up and become irritating, making your text genuinely unpleasant to read, or even unreadable.

Check your facts and be sure of them. Clearly separate your own opinions from factual statements.

Do not work in a vacuum. Read other people's work. Look for good writing, and don't just passively experience that writing, focus hard on it so you can see what makes it effective. Take notes. Have other people read your work, and if possible cajole them into giving you notes in turn. Make sure that you are not the best writer you know.

And for the love of God, use libraries!

Back to Blog
Back to Things Of Interest

Discussion (13)

2016-06-24 18:17:17 by qntm:

I found this in my archives dated 2015-01-18. It looks like I wrote it but never published it then, but it seems okay to me, so I'm publishing it now.

Naturally, a piece of writing which reads like a computer program is not necessarily a good piece of writing. Much of this advice is wrong if you wish to write *unlike* a programmer, or, for example, write like yourself.

Some of the less defensible statements are: "every line of your text must serve this objective", "avoid idioms", "group statements according to purpose and subject matter".

Anyway.

2016-06-24 18:33:05 by qntm:

Also "avoid ambiguity" and "try not to refer to topics or terms before they have been adequately introduced" are probably not good suggestions for e.g. fiction.

2016-06-24 19:31:05 by Sempre:

This was a good read. Thanks.

2016-06-25 02:06:12 by Tim McCormack:

Also, use source control! :-D

2016-06-25 20:56:54 by Nobody:

Just wanted to tell you that your "To Destroy the Earth" essay has been quoted here:

https://www.fanfiction.net/s/11725301/20/Around-the-World

2016-06-26 01:31:11 by gfody:

This is great! I love comparing programming to writing when I'm trying to make some point for better programming. Another aspect is how the rules of classical rhetoric relate to SOLID principles - in that you can't become better by just studying these rules. Because great writing came first and the rules were invented after-the-fact in attempt to emulate it.

2016-07-06 05:47:57 by atomicthumbs:

this is also applicable to every form of art, from what i've found

2016-08-10 16:11:47 by yatima2975:

If programming is like writing, then what corresponds to comments? Footnotes? Or snippets of code in the story/text?

2016-08-11 08:10:41 by wolfgang:

I like the article, but I am missing the structure:

If you add some headlines, it is easier to grab.

2016-08-17 08:56:17 by pepoluan:

Ahaha, awesome!

I do casual writing (fanfictions), and yeah, 1st drafts often only bear passing resemblances to final version.

Kind of similar to the programs and libs I've made. v0.1 will be a sad, embarrassing history of v1.0. Classes remade. Convoluted procedures which made me think, "What the hell was I thinking when I wrote it this way?" APIs change.

Awesome article!

@yatima2975 comments in codes will be Author's Notes, be it personal or public (published). Something *very* important in worldbuilding a massive fiction.

2016-10-20 18:44:01 by KA:

I felt you were sitting next to me telling this. WOW

2016-12-21 15:52:11 by zoug:

Thank you for this!

2017-01-29 00:17:55 by Redsplinter:

I feel like a lot of teachers could use this post, verbatim, and be deemed _good teachers_ on that alone.

That said, particularly because it came so close after the point you made on clarity, I'd add in a parenthetical or italic blurb after "format consistently," (e.g. "_and clearly if not correctly_", etc.)

Basically, readability is paramount, traditional correctness is not. ...Unless you're taking a grammar test.