Programming as Writing

I would completely agree with Eric Lippert when he says code is way easier to write than it is to read.

In programming, as in writing, we present text and data. Data without structure is useless. How do I find things? How do I consume information? What is important and what is trivial?

When you read something, you expect a certain structure that saves your time and effort.. in the absence of which, you quickly give up. Let's look at a few things that affect writing and programming in the same way.

Important Information Goes First

Table of contents, indexes and overviews should come first. They present a bigger picture to the reader. They help the reader to navigate through the content in a very smooth manner. Then comes the titles and then the paragraphs.

In programming, overview is typically represented by package structure, and tiers. It isn’t as easy as it seems. It is extremely important to confirm to a structure and stick to it consistently throughout the content.

The titles, which would be method and class names, have to define what the following content is going to be. Well written title gets noticed and communicates the intent of the paragraph to the reader.

Then the paragraphs. It is extremely essential to break your content into many paragraphs. A carefully structured and organized content goes a long way in capturing the reader’s attention compared to a single large piece of content. So it's important to break our code into proper classes and methods and keep them small and contextual.

Combination of small and well crafted classes and methods with well positioned names for them is a perfect recipe for fantastic prose.

Structure of Information

You can structure your information in a number of formats that can appeal to the reader. If you understand your readers well and can prioritize the important parts of your information, it's wonderful. You can structure your information in the order of importance.

There are many layouts like Hierarchical, Linear, Non-linear, etc. Here’s a good example of a typical structure of a program.

Search-ability

You can provide extreme help to your readers if you make your content easily searchable. That means, readers can reach the content that they’re interested in, very easily.

Especially in software, since readers do not go through every piece of code line-by-line, it makes lot of sense to produce content that is very easy to search. Few things that can be done are:

• Maintain the same vocabulary throughout the project. So when you name a variable as ‘salesTax’ at one place, it’d help a lot if you use the same variable name at other places in the code too, making context specific searches extremely easy.
• Name your classes and variables in terms of domain related terms. So instead of a class named ‘SingletonFactory’, it’d be nice to have a name as ‘AccountManager’ or something closer to the domain.
• Keep the content and the titles in the same context. So if a method says ‘calculateTax’, it should do only that. Other side-effects like auditing, interests should not be part of the method. They can be placed in their own methods or classes.

Getting a Second Opinion

It's easy to get lost in your own world and miss out many details. So periodically, one should review their content with few other readers. This would help you validate your assumptions and provide valuable feedback to improve on your writing. You can start out by giving an overview of the content that you’ve written and then let readers find their way out through it. Observe them as they’re going through your content and how they’re navigating through the different structures.

In software programming, the process is called code reviews. This is where other programmers have a look at your code and provide their feedback. It is extremely important that you do that more often in your whole effort.

Read Others

It's amazing to see how related reading and writing are. Once you start reading other people’s content, it has an effect on your own writing style. You tend to appreciate and adapt other people’s style and presentation of content. When you write, you try to accommodate those learnings yourself.

You can setup reading groups to improve on your skills. Doing it as a community is extremely effective as you can discuss your views and assumptions with other people in the group and form a very objective opinion.

For programming, there is so much good code out there to be consumed. Start off with your favorite open source code and try to identify the patterns and styles that are used in that code. Try implementing those in your code as well.

Conclusion

In the end, it's extremely important that you write. There’s nothing like writing. The whole process of writing improves your process of thinking too. Once you start thinking clearly, the same would show in your code. I believe writing (as in prose..) can have a very positive influence on your skills as a programmer.

So... let's write. Lots of it.

CodeProject