Skip to content

On writing (code) well

On Writing (Code) Well

A month ago I had the pleasure to go to one of our local Java User Group events – “jProfessionals: Java Day with Venkat”. It was a whole day packed with two talks and a lab, presented by Venkat Subramaniam.

In one of his talks, named “Twelve Ways to Make Code Suck Less” something a little odd happened. Venkat recommended us a book. Nothing strange about that, except this was not a book about programming. It was a book about writing. Why is a renowned Java lector recommending the principles described in a book named “On Writing Well”? We are writing code, executed by a machine, not a book written for people.

“On Writing Well” is the the classic textbook of how to write nonfiction. I have heard about it before, as other people (writers) recommended it to me.

When the book was mentioned in completely different context, it was time to finally buy a copy and read it.

The link between writing and programming

Buying the book and the whole experience made me think about the link between writing and programming.

Turns out, they are not so different as I thought!

Both are a craft. You learn craft by doing. Definitely true for both.

Code is something you write in programs. It is a series of instructions you send and in the end you achieve the desired result.

Words are also code. They code your ideas in your mind and in the mind of your reader. Reader can then act and execute on those ideas, even “reprogram” itself. This is your way to influence the minds of others or even your own. Doesn’t sound that different now isn’t it?

Books are programs and good book authors are some of the greatest hackers.

You can find parallels even in the process of writing words and code.

Suppose you are writing an email on your computer. You write as much as you can, then you check it, than you revise it. Just like you write and refactor your code when you program. You rewrite and remove until cannot remove more. When you are sure you have communicated your ideas you stop. Or when you run out of time.

“Perfection is Achieved Not When There Is Nothing More to Add, But When There Is Nothing Left to Take Away” Antoine de Saint-Exupery

Principles on writing

This brings us to Venkat’s presentation and his rule #6 for making code suck less – “Apply Zinsser’s Principles on writing” (to your code).

William Zinsser is the author of “On Writing Well”. In his book he describes four principles of good writing. Here they are:

  • Clarity
  • Simplicity
  • Brevity
  • Humanity

I’ll revising each and how they relate to programming.


Whatever is that you write, it should be clear. Clarity is the goal of writing. Program code goal is usually seen as something that is going to be repeatedly executed by a machine. That is, until you need to read some code, to figure out how it is doing what it is supposed to do.

Good code reveals intent.

It will tell you, in a clear way, what is going on and what was the intention of the person that wrote it.

This is why we programmers spend so much time naming things. Because we know we need good variables, method names, carefully named classes, modules and projects. We know that we should communicate the intention of our code, so we spend a lot of time naming things.


Simple words are better. Want to say something important that other people will understand? Imagine you are speaking to your children.

It is not about showing off how much you know and how clever you are. Avoid complex, sophisticated words that experts use so often. Say it simple. Prefer clear language that is easy to understand.

Once again, what is true for writing is true for code. Simple code is easier to understand, no doubt about it.

Avoid any complex logic, multiple loops, multiple if / else statements, shared variables and state, dealing with many dependencies.

Many people mistake complex and clever code with good code.

When you show your clever code to your colleagues, they are first like “Dude, wtf is this?”. But wait, just you wait! They will get it! Minutes later and they are now like “Amazing! You can do that?”, congratulating you on the hack well done.

Clever complex code makes you feel good, isn’t it?

Avoid the “Hey, look at what I can do it just 2 lines of code” trap.

Code should be simple to understand. This is not a competition who can do a task in least amount of lines or use obscure functionality nobody’s heard of before.

Good code is simple (boring) code.


Short is better.

Words, sentences, paragraphs, chapters, books, methods, classes, programs.

All are better when they are short. It makes it easier for people to hold them in their minds.

When you write, you write your ideas into sentences. Communicate one idea at a time. Explain one at a time. It is the same as code isn’t it?

Keep your methods, classes and even programs shorter, doing one thing at a time. Write only what is needed and nothing more. Do not pass anything that not needed.


This is the most important principle and perhaps the one that is the least obviously linked to programming from them all.

When you write a book, you write it for a person to read.

When you write a program, remember you are writing to a person as well, not to a soulless machine.

Code is how we tell our colleagues how we feel about them

Well, that’s it! Please share it if you liked it!

Thank you for reading.