Write Like A Programmer

I program computers and I also write. There is more than one way to program, and there is more than one way to write. And there are a few good practices in programming which have analogous good practices in writing. Here is how you write like a programmer. If you want to write like that. Which you may not. 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!

Discussion (23)

2016-06-24 19: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 19: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 20:31:05 by Sempre:

This was a good read. Thanks.

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

Also, use source control! :-D

2016-06-25 21: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 02: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 06:47:57 by atomicthumbs:

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

2016-08-10 17: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 09: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 09: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 19: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.

2017-05-15 18:36:25 by Kate:

This post really hit the spot! Thanks for the advice. You gave such a great breakdown on how to write and think like a programmer. <br> Writing is not my strong suite; when I have to write articles related to the <a href="http://www.impcorporation.com/">oil and gas</a> industry I go into major writer's block, or my paper reads extremely messy. <br> I definitely needed this, thanks!

2017-06-19 20:10:26 by gwl:

@yatima2975 I'd say comments are the equivalent in writing. as in just a little note you make that you delete on the final version. heck, in web based publishing you can keep them there as only visible in the source code.

2017-11-13 15:14:30 by Tahrey:

Heh, sounds a bit like what I do, but more drawn out. I just wish a) I had the time to devote to each text properly, and b) people *actually* seemed to prefer reading things written that way. Problem is, they don't :-( Well, not that much anyway. *I* like reading it. Which is why I'm happy to come across, say, your works... one can't read their own stuff alone without going mad. (OK, that's an exaggeration for comic effect; it's not that I *only* like that style, it's just that it's within the styles that I enjoy but, I find, not so commonly within the preferences of others)

2017-11-13 15:17:47 by Tahrey:

*casts around the site more* *hits the reddit link* *sees a particular topic that catches the eye* *follows* Dude ... you're an SCP author as well? And 055 just for one? *fan-squeeling* Forget what I put above, obviously I'm misinterpreting ^_^ (yeah, maybe it's less common than arriving via The Foundation these days, but I've teleported in from E2...)

2018-01-05 14:44:04 by Tom:

"Avoid idioms" is good advice for prose, not so much for programming. Usually, the goal in programming is to communicate to subsequent programmers trying to fix or enhance the code, so I consider it good practice to employ idioms wherever possible to make it easy to understand my code quickly.

2019-12-31 10:49:03 by Daniel Bensen:

What excellent advice! I'm sharing this extensively. Interestingly, your "write with a purpose" advice is very similar to the advice of Lisa Nichols. She isn't a programmer at all, but she says a writer should write for the at least one person in the world who needs this book. In that spirit, I think people need to read your advice on deleting paragraphs. There isn't some resevoir of words or ideas that's being depleted as you write - there's always more, and better. A lot of writers need to hear that, because they do think they're exhausting some resource when they write, and that's bad for their health. It certainly was bad for mine. I would argue for a higher priority given to collaboriation, though, either with co-authors or beta-readers. I'm currently working on finding and getting help from people who disagree with. Also there comes a point at which you have to learn how to turn off your critical reading and just immerse yourself in a book for fun. I have a great deal of trouble with reading for fun now adays, especially in science fiction, because I fall into critique mode and the story falls apart. That's a challange. Once again, thank you! Now to share this post.

2020-01-06 17:46:24 by mwchase:

It just occurred to me about "avoid idioms", it depends on the definition of "idiom" being used. We've got "a group of words established by usage as having a meaning not deducible from those of the individual words (e.g., rain cats and dogs, see the light ).", which have equivalents in the shape of confusing APIs or nonsensical overloads, and "a characteristic mode of expression in music or art." which is the sense that's likely to be used positively.

2020-06-30 03:09:40 by Jed:

Hm. This is pretty good, but if you're interested in this kind of writing you ought to read <a href="http://classicprose.com/">this book</a>, which refines these ideas into an instrument of high literary style. Even if you prefer another style, reading that book will teach you a lot about what style is (it is not undefinable, as many writing teachers believe), how to cultivate one or a few, etc. It will make you a better writer.

2022-06-23 21:22:10 by Spinnaker:

I stumbled across this article after reading the SCP antimemetics stories, and I think it's bloody brilliant; It's helped me think far more about some of the strategies I unconsciously tried to use when writing. Editing as a matter of hand was obvious for me - treating it like refactoring, like a planned process, was was not. The point about brevity I especially liked - I have a personal vendetta against coders who obsess over doing things with as few lines of code and as many implicit tricks as possible, and yet I never fully extended that line of thinking to writing. Dunno if you still have any notifications on, but you can consider this a thank you message.

2024-01-16 03:57:59 by tones:

Kingsley Amis is purported to have said "Write drunk, edit sober."

New comment by :

Plain text only. Line breaks become <br/>
The square root of minus one: