Programmer Musings

LCDC: Different Audiences Have Different Needs

In the last few posts, beginning with The Myth of Code Anyone Can Read, I've focused on what you can expect from your programmers in general. Of course, generalizing is what got us into this discussion in the first place, so let's spend a little time not generalizing.

When teaching new programmers, I always tell them that the code had at least two audiences: the computer and the next programmer. This is not actually true, depending on the purpose of the code, it may have many audiences. For instance,

1. Code used as an example to show how to use an API, may be used by almost any level of developer. They may not have any experience with your system and may be relatively junior.

2. Code used as examples for writing plugins for your system can expect that the reader has some level of familiarity with the way your system works, if only at a superficial level. Since plugins normally have a tighter integration with your system than an API call, the developer can be expected to learn a little more before doing development.

3. Most of the code in any given system is non-critical. If non-critical code breaks, it is annoying and possibly embarrassing, but it won't result in loss of data or compromise of a customer. Since it is inside the system, any developer working on it will have at least the level of expertise that the manager hires for. If every new hire is expected to have three years development experience, the code can assume that level of experience.

4. Core business code is the part that makes the money. The programmers that are working on that code should be at least the level of experience you hire for, and probably more. They should be familiar with the business and terminology, so that they can be expected to understand the jargon.

5. Core library code is the foundation upon which all of your system sits. Some of this will be libraries that you have gotten from a third party and just use. Some will be the low-level routines written by your senior developers and used by the rest of the team. This code requires deep knowledge of the domain of that library. The only people working on it will be experts in that particular domain. Only the most senior people should be making changes in this code.

Levels of Developer

Let's start with a fundamental rule:

Expertise is not evenly distributed.

This rule is why programmers (and people in general) are not interchangeable. You cannot expect to replace the senior programmer, who has 5 years of experience in your code base, with an entry-level programmer straight out of a computer science degree and expect the same level of productivity.

I have had some people suggest that this is an elitist approach to development. As a really new programmer, I would have been insulted by someone suggesting that I wasn't qualified to work on a particular piece of code. In actuality, this is really more of a pragmatic view of development than an elitist one.

The truth is that developers in the real world have different levels of experience, along many different dimensions. Some are experts in the language, but know nothing about your business. Some know about your business and have never written more than a 10 line program. Most are somewhere in-between.

API User

Let's take the first category, people who use our APIs are completely outside our control. We have no knowledge of who they are or what they have worked on. For this reason, we pretty much have to assume LCDC as a requirement. This is as close to random person walking in off the street as you should get. Anyone who has ever supported an API has stories of people misusing the API for many reasons including:

• Using the API for the wrong business.
• Trying to perform an action that is not valid for the industry
• Using the API to violate the laws of physics
• Trying to use the API from an unsupported language
• Trying to use the API with unsupported hardware

My favorite example of this was a system I supported that displayed charts of stock price information. We had a customer trying to use our interface that reported a bug. No matter what he did, he could not get the chart to show data later than today. It took a bit of effort to explain the impossibility of displaying tomorrow's stock price.<shrug/>

You can assume nothing about a user of your external API.

Plugin Developer

Even if the plugin developer may start near the same level as someone who uses your API, they will inevitably become more knowledgeable before they get very far into the development of a plugin. By their nature, most plugins require some understanding of the system. Most of the time, someone has used the program itself and possibly any API for a while before deciding that a plugin is the way to go.

Since developing a plugin requires more expertise and knowledge, it serves as kind of a filter on the kind of developer will attempt it. By structuring your plugin interface for more experienced developers, you can further filter for developers with the kinds of skills you are willing to support.

Business Code

The next two categories of code will mostly only be seen by your developers. Most of this code is not business critical. A large amount of any code base is normal input code, validation, data-massaging, and output. Support for templates, language, user interface, etc. are important, but may not harm your customers in the event of a mistake.

Most business, however, have some code that is core to the business. Some examples include:

• makes the money (charging credit cards, making trades, finding oil, etc.)
• handles the consistency of the user's data
• handles legal requirements
• prevents unauthorized access to private user data (credit card number, etc.)

All of that kind of critical code is not immediately turned over to junior developers, because mistakes in those areas could mean failure of the project (or lawsuits or loss of income). The more critical the code is to your business the more likely you are to have it done or, at least, overseen by more senior people. This is simply because your most experienced people are more likely to be aware of the issues that are important in this code.

That Code

Many systems have a piece of code that is core to their business, but is so involved, low-level, or just plain weird that only a few are trusted to touch it. This code normally lives in libraries that any of your developers can use, but few understand. Sometimes it's the result of someone determined to have job security because they are the only one who understands the code. Most of the time the reason is more benign. This code could be:

• the result of someone's PhD thesis and only a handful of people on the planet understand it
• the system that ensures that data is maintained according to the laws governing your industry
• the trade secret that allows your code to do something your competitors can't
• the interface code to a piece of hardware required by your system
• the registration code that makes certain your company is paid for every copy in use

In most cases, this code is important and a small number of developers have become the experts with that code over time. (Hopefully, that small number is not 1 or less.)

This kind of code often has special jargon all its own that no one new to the system is going to understand. There is really no need to make this code generally understandable. You do not want a junior developer making changes here, since there is a large probability that they are going to break it.

Different Styles for Different Audiences

Different portions of the code assume different levels of expertise from their audience. Trying to write all of the code to the least common denominator will make parts of the code unfit for the designed purpose. An approach that cannot assume some knowledge of the part of the developer will be harder to maintain for people who do have that knowledge.

Realizing the audience for a particular piece of code will allow your team to choose an appropriate level at which to write the code, instead of mandating a bad idea. One other side effect is that someone wandering into code that uses more advanced idioms, that they don't understand, has an indication that they should probably know more before making changes here. It's kind of a you must be this tall to ride the ride sort of marker.

If the code is written as if any idiot can change it, likely one will. This approach only works if your developers are comfortable with the idea that code may be written with different idioms and that the idiom is an indication of expertise needed. It also works better if anyone is allowed to read the code, but only allowed to change it once they have convinced the current maintainers that they have the appropriate understanding.

Summary

Different kinds of code require different levels of expertise. Writing everything as LCDC, hides useful markers of different kinds of code. This could tempt less experienced developers into breaking critical code because they touched something they didn't understand.

In the final post of this series, I'll show that this is not a static situation.