Programmer Musings

Write for Your Audience

My wife is a really good writer and she once gave me a great piece of advice for some documentation I was working on: Know Your Audience. This has helped me to write better documentation. Over the years, I have come to realize that the same advice applies when writing code.

Who is the Audience

Most junior programmers only worry about getting the syntax right. After all, if the code compiles they are finished. Eventually, most programmers realize that the code is read by other people more than it is compiled. So writing code that is understandable to others is extremely important. In fact, all code is written for at least two audiences: the computer and any programmers that will read the code in the future.

The computer (actually either the compiler or an interpreter) is an easy audience to please. If the computer doesn't understand the code, it fails to compile. The human audience is much harder to reach effectively. This fact is what makes more senior programmers focus on details like consistency, the naming of variables and functions, and white space, where a more junior programmer might not.

In fact, knowing that the important audience for the code is another human is not enough. You need to have some understanding of what the reader of the code is trying to get from or do with the code. You also need to be aware of the level of expertise of the readers of the code.

Me

Most junior programmers write the code for themselves if they write it for anyone. Some of that is because they don't know any other audience. The code could be written at any level of understanding, because the programmer involved could be writing at any level of expertise.

The biggest shock to this kind of developer is when they come back to some code months or years later and realize that they can't understand it. They are no longer the target audience. This can be a humbling experience.

The Random Person

I have worked on some projects where the coding standards basically state that any programmer walking in off the street should be able to read the code. No advanced language features are allowed. No advanced programming techniques are allowed. Jargon or project-specific terminology is discouraged.

Not long ago, the XKCD web comic did a wonderful example of what happens when you try too hard to simplify language. The Up Goer Five comic describes the Saturn V rocket using only the ten hundred most commonly used English words. (Note that thousand was not on the list, so...) This is a really good example in English of what most programmers see when they look at code written with the Random Person audience requirement.

I've actually had people go so far as to suggest that the code should be readable by someone who doesn't know the language. I'm really not sure what kind of constructive comment you can make in that case. The code equivalent here is to use the simplest language constructs, simple programming concepts, and as little project-specific terminology as possible. While this makes it possible for someone to read the code without much prior knowledge, it pretty much negates any prior knowledge the reader does have.

Expert Programmer

If the people reading the code can be expected to be experts at general programming or at least experts with the language in question, we can allow the code to contain more powerful language constructs. Meta-programming, functional techniques, and design patterns are all available.

A lack of domain or project knowledge may still constrain the jargon that can be used in this case. Good documentation, including explanatory inline commentary can help bridge these knowledge gaps. But, you can assume that the reader will understand the code itself. This allows for concise and powerful coding idioms that can result in a much smaller code base.

Domain Expert

The reader could be an expert in the domain or project, but not necessarily an expert programmer. This audience would allow the code to be written more in the domain of the problem, but the code itself might not use more powerful idioms. This is often the goal if non-programmers will need to understand the system. Some literature refers to writing in the problem domain to cover this case.

Full Expert

The least restrictive audience would be one that has deep knowledge of programming concepts, the programming language in question, and the project itself. You would expect this audience to be able to understand large amounts of the code with only a cursory read. Their familiarity with the domain and deep knowledge of programming allows a very concise and elegant approach to writing the code.

Choosing the Audience

One approach to choosing your audience is to select one kind of audience and write all code with them in mind. If the project only has a single programmer this often results in an audience of Me. That approach begins to fail as soon as you start adding more people to the project.

In the project has several people and a coding standard, then the single audience case normally aims for Random Person. The second case often seems attractive to the owners of the project. The main problem with this second approach is the fact that expertise on the part of the reader gives no benefit. If your code is always only read by junior programmers who are not on the project for long enough to develop any domain expertise, this might be a viable option. On the other hand, more experienced developers will probably leave to find somewhere that their skills are more needed.

Not Just One Audience

With any long running project, there are likely to be examples of each of the audiences above working on the project or reading the code at any given point in time. If you don't allow at least some of the code to encode knowledge and expertise, your more senior people will become frustrated and leave. If your code is only written for the most experienced, bringing in new developers will be hard.

In a real project, different parts of the code probably have different audiences. The most central algorithms that are the core of the code may actually be complicated and require real expertise to understand and change. This code can be written in expecting a truly expert audience, because only someone who really understands the code should try to change it anyway. (A friend of mine described this as the you must be this tall to touch this code approach. Basically, if you can't understand why it was written this way, you may not be qualified to modify the code.)

Many systems provide an API for people outside the project to use. Obviously, this code should be written for an audience with much less knowledge of the system (and less of an expectation of general knowledge or expertise). Code written around the public interface for the system cannot assume extensive experience on the part of the reader. This code should probably default to simpler idioms.

Code in between these two extremes should take into account the level of developer you expect to need to work on that code. By providing code written at multiple levels of expertise, new developers can work on the simpler code as they develop the expertise needed to more to more advanced sections. Experts can work on the core code where their expertise can provide the most benefit.

Conclusion

Code will be read more than it will be compiled. A good programmer will give some thought about the audience of different pieces of the code and write accordingly.