Why Write?

If you write software, you are a writer. Your target audiences are computers and people. Reading Java or C++ code has no where near the entertainment value of reading Edmund Morris¹. But, Edmund Morris has the luxury of writing solely for people, software includes computers. Navigating the two audiences of software is a continual struggle for all engineers. Writing clearly, succinctly, and beautifully is hard enough for one audience. Achieving this with two? Monumental. Well written software can reflect well written non-fiction in many ways. What can software engineers learn from the principles of great non-fiction?² Clarity, words, and flow are all necessary for other engineers to understand our systems.

Achieving Clarity

Clarity is a hallmark of good non-fiction. The facts not being muddled with complexity. The sentences not being held hostage by the writers “creativity”. Well written software should reflect this. An example of lost clarity can be seen in some contrived Java

class Baz {
    private String bar;

    ... // largish class definition

    public void foo(String... parameters) {
        ... // long method
        bar = otherString;
        ... // rest of method
    }
}

Is bar a local variable to Baz#foo or the class field? Without double checking our context, we will not know. If foo is significantly complex, the reader will never know. Luckily, IDEs have become more advanced and they give helpful signals when a variable is actually a field. But, what if you are not using a full fledged IDE? A simple addition of this.bar addresses the clarity problem. The reader now knows exactly what is happening. There are other problems with this code. What is Baz? How can I know what it does when it has this non-descript name?

Words

Many say the two hardest things in software are cache invalidation and naming things. Using the appropriate words to name a variable, function, class, or in writing a comment are a constant struggles. The work of writing forces word choices with explicit meanings and visual imagery. Ruby on Rails is an excellent example of carefully, and sometimes a bit too creatively, chosen words. Though it has many faults, it is a shining example of well chosen words³. The classes, callbacks, functions show their specific, and layered uses through carefully chosen names. But be warned, being overly clever can cause pains. If something is a callback, name it such. Do not call it a demon because it is “summoned” when a specific “ritual” is completed. Using unfamiliar, or ambiguous words can not only hurt understanding but also the readers flow.

Flow

When reading a well written article, or book, your eyes seem to jump from word to word. You are being pulled forward by the narrative. The writer has achieved a natural flow of logic, facts, and words that allows your mind to let go and float along with the author. Good software also has a flow. There are not logical leaps or jarring pivots. Each step clearly follows the other.

int[] position1 = new int[]{1, 2, 3, 4};
int[] position2 = new int[]{5, 6, 7, 8};
int squaredEuclidean = IntStream.range(0, Math.min(position1.length, position2.length))
                                .map(i -> position1[i] - position2[i])
                                .map(i -> i * i)
                                .reduce(Integer::sum);
int euclidean = Math.sqrt(squaredEuclidean);

No breaks in flow. Each logical step follows the other. This can be difficult to achieve in sufficiently complex systems or even detrimental to the main audience - the computer. But, that does not mean it should not be attempted and achieved were possible.

We are writers

I have been writing software for a couple of years now (~5 at the time of this writing). I want to master my craft and writing well is a prerequisite. I have put off this practice long enough. I am a writer, whether I like it or not. Better be a good one.

1 If you have not read his trilogy on US President Theodore Roosevelt, you are missing out. ↩

2 These principles, and many of the passages used come from On Writing Well by William Zinsser. Even if you disagree with my premise around software, I am sure you will find this book informative and fun. ↩

3 Though DHH can be controversial, his playfulness and practicality in choosing the correct word has shown through in Rails, and it is better for it. Watch his On Writing Software Series↩

4 Software has equally over used, TODO:

for(int i = 0…), Singletons, FactoryGeneratorPatternFactory…. ↩