Writers are interesting people. They spend all their time with words. They obsess over the smallest details. They polish and revise. E.B. White once wrote that "english composition is . . . a way to spend one's days." Hemingway literally did just that. He worked on a single sentence until he was satisfied, and that often meant he finished just a sentence a day.
Programmers also spend a lot of time with words, and there's surprisingly more overlap to writing than most people think. Donald Knuth once observed that:
"A programmer is ideally an essayist who works with traditional aesthetic and literary forms as well as mathematical concepts, to communicate the way that an algorithm works and to convince a reader that the results will be correct." —Donald Knuth
I hold degrees in both Writing and Computer Science. I've also workshopped with professional writers and had both fiction and non-fiction published. Below I will mention five things that I learned from writers (and writing) that have also helped me write good code.
1. Writing code helps you understand your problem better.
Writers often encourage writing as a means to understanding and discovery.
"Writing is like driving at night in the fog. You can only see as far as your headlights, but you can make the whole trip that way." —E.L. Doctorow
One major idea I've taken from this is that writing code is often not the result but merely the journey. Write some code. Then throw it out and write it again a different way. Your solutions will become more elegant.
I came across this great tweet from Mario Fusco while I was writing this which summarizes this idea:
2. Omit needless code.
If I had more time, I would have written a shorter letter. —Mark Twain
By saying this, Twain meant that it's actually harder to write less. If you spend any time with editors, you begin to see that there are many unnecessary words in your writing. In On Writing, Stephen King mentions that the first stories he submitted to a newspaper editor were usually cut in half under the editor's knife.
Writers revere a book called The Elements of Style and the sentence, "Omit needless words" is actually one of its "rules." It is also an example of how to do just that.
Similarly, shorter code is usually clearer. If you have a Car class with a method to drive it, name the method drive() not driveCar(). Otherwise, you'll end up with redundant statements like car.driveCar().
And if a library or functional construct exists for something you want to do, use it. Don't loop through a collection to sum up some total. Stream it and sum.
Not:
int totalPages = 0;
for(Chapter c : chapters) {
totalPages += c.pageCount();
}
return totalPages;
But:
return chapters.stream().mapToInt(Chapter::pageCount).sum();
Shorter code is more expressive.
3. Know your audience
Writers also spend time to make sure they are speaking to a specific audience. An older generation of readers won't think twice about phrases like "dial him up." But phones don't have dials anymore and hardly anyone says that. Even so, it might still be appropriate for the latest issue of AARP The Magazine.
It's all about audience. What is your code's audience? I think it's mostly the other programmers on your team, present and future. Donald Knuth has a great thought about this:
Let us change our traditional attitude to the construction of programs. Instead of imagining that our main task is to instruct a computer what to do, let us concentrate rather on explaining to human beings what we want a computer to do. —Donald Knuth
Just like writing, code should look familiar to its audience. Whenever possible, it should adhere to known idioms and avoid clever tricks. That way there's fewer mental gymnastics necessary for your teammates to understand it. If your code doesn't clearly communicate what it's doing, are you a good coder? One way to improve code is to write it from the mindset that your best chance at getting the solution across to them is to write it in their language.
This is most important when naming classes, methods, and variables. Naming is famously one of the hardest parts of programming. It's mentioned in the famous joke:
"There are two unsolved problems in computer science: cache invalidation, naming, and off-by-one errors." —Unknown
If everyone understands the word, advertisement, in a specific way, use it. But if there's ambiguity, find something more specific. Is it a print advertisement? Email? Text?
Although inelegant, using adjectives or modifiers to describe exactly which kind of advertising is meant (EmailAdvertisement) is one solution. Another is to think more deeply or broadly about the use case and find the word that the most people grasp intuitively. Maybe what the code is really modeling is an email marketing campaign. Perhaps there's a word that businesspeople in your company already use all the time for this. If everyone calls it an email campaign, your code should too.
I've always been a fan of domain-driven design for its concept of the ubiquitous language.
To communicate effectively, the code must be based on the same language used to write the requirements—the same language that the developers speak with each other and with domain experts. —Eric Evans
Writing code in your domain's ubiquitous language is one possible way of being specific and communicating to your audience. There are, of course, many others.
4. Write what you know
Write what you know is a piece of advice every writer has heard. Yet it is usually misunderstood. You might think, if I only write what I know, I must be writing memoir then?
Melissa Donovan has a great article about the write what you know mantra, and she summarizes its meaning well:
"To write what you know does not mean you only write about experiences you’ve had, people you’ve met, or places you’ve been. It means you use what you know about life, nature, and humanity as the foundation for your stories." —Melissa Donovan
How does that apply to code? It means code should manifest something of the real world. Code isn't its own separate entity. It lives alongside or maybe even inside your business context. As a software engineer, then, it is a reminder that most of your job is about understanding the user and their task. Write what you know.
5. Write!
But the best thing I've learned from writers is simply to write! Write a lot! Most writers will tell you that you absolutely must write every day if you want to be a great writer. Writing often is the number one piece of advice writers dispense.
"Write all the time. I believe in writing every day, at least a thousand words a day. We have a strange idea about writing: that it can be done, and done well, without a great deal of effort. Dancers practice every day, musicians practice every day, even when they are at the peak of their careers – especially then. Somehow, we don’t take writing as seriously. But writing – writing wonderfully – takes just as much dedication." — Theodora Goss
This idea from Theodora Goss is also echoed in quotes from Ray Bradbury, T.S. Eliot, Orson Scott Card, and many others.
So write code. Write code all the time. Write code every day. Writing code takes dedication. Consider doing code katas or going through Project Euler. Your code will show it, and your fellow programmers will appreciate it.
Conclusion
I hope these programming tricks have been helpful. If you have any more that you've learned from writers or from writing, I'd love to read your comments below.
Happy (code) writing!
Top comments (8)
Great article.
A trick I picked up from writers was to proofread your code backwards when looking for bugs.
It sounds strange, but when proofreading professional writing, reading it backwards changes how the brain processes the information revealing bugs you might otherwise miss.
In this age of over-reliance on tools, many basic concepts of debugging aren't taught or learned hobbling beginners and many alleged "professionals" alike. As such when they butt heads with an issue the tool isn't handling for them the developers end up hobbled by their lack of the basics.
Something as simple as just reading through it backwards instead of blindly hoping that a tool will do the work for you is shockingly effective.
Now that's awesome! Thanks for the tip!
Wow! Great article! I studied a lot of writing-intensive courses in school and once I realized that coding is a lot like writing an essay, short story, article, etc, I became much more confident in my problem-solving abilities. So cool that I am not alone in thinking this way!
Love this quote (and all its different versions). A similar thought comes from Elmore Leonard:
If it's the kind of code I hate to read, then it's not the kind of code I should write.
Writers have so much to teach us developers. And -- lucky for us -- they're good at expressing themselves. After all, that's their job.
Great article Scott. Thank you!
excellent article, thank you!
Great advice straight through!
I do indeed try to live by The Elements of Style. ;)
Thank you for this. Really enjoyed reading this article.
Write what you know, unless you want to write what you don't know.