Spence Green

Software engineers do not often have the luxury of designing new systems from first principles. It is frequently the case that they must labor through some dreary chore, such as implementing version 49 of the SuperWhamo! application, or adhering to design constraints imposed not by reason, but by suits. When that rare opportunity to write new code does present itself, two paths are possible. The coder leaps into development, but the architect tries first to solve the problem. This essay contains my observations on the latter approach.

Solve the Problem
Every good system solves a problem, which is often elusive. Think about any famous product and try to describe it with a single sentence or a single image. What does the iPod do? It allows you carry digital audio with you. Google? It lets you find relevant stuff on the Internet. Linux? The world needs a good, free operating system. This is not a pedantic exercise. It took me three months of reading and observation to discover the purpose of a recent project. Not a single person in our organization could articulate the system’s raison d’etre clearly, and I found that when I could, my design work took on a new level of coherence. What does the system do and why does it do it? Why is it useful? Answering these questions can go a long way toward unifying the design process. If the questions can’t be answered, then it might be prudent to get real and kill the project.

Write It Down
Once the system concept becomes clear, write a detailed spec. Specs serve several purposes:

• A reason to think: Writing is a specific activity whereas conversation and drawing are often unspecific. If you write, “The system should have a login page,” and then reflect on that statement, then you immediately realize the need for more detail. What does the page look like? What screen elements does it have? What text does it display? The answers to these questions are all requirements that go into the spec.
• A common design decision repository: The login page’s design details need a persistent home. Engineers, just like football players, need to operate from a common playbook. This is why email, PowerPoint, and the lauded whiteboard are not suitable design media: they are not permanent.
• A context: Our system has more than a login page. What is the next page in the interface hierarchy? How does authentication work? Where is user information stored? It is impossible to construct software without knowledge of context.

Software specs exist in myriad degrees of formality, breadth, and depth. But the most important thing is that they exist at the beginning:

Writing a spec is a great way to nail down all those irritating design decisions, large and small, that get covered up if you don’t have a spec. Even small decisions can get nailed down with a spec. For example, if you’re building a web site with membership, you might all agree that if the user forgets their password, you’ll mail it to them. Great. But that’s not enough to write the code. To write the code, you need to know the actual words in that email.

I don’t advocate Joel’s informal approach to specs. His method may be sufficient for designing web sites and business systems, but it cannot be used for Space Shuttle avionics or air defense systems. You wouldn’t use the instructions that came with your Coleman tent to build the Empire State building. The IEEE830-1998 standard is a better reference.

Draw It
Any software architect will quickly learn that it is difficult to model a system in its entirety. The software blueprint will probably never exist, a conclusion reached by the Agile crowd a decade ago. Metaformats suffer from a variety of issues, including:

• Inability to represent the whole system: The UML As Blueprint people have in mind the “exploded” view of systems that is so useful to mechanical engineers. Software is not tangible, though, meaning that it can behave strangely. Try to model a recursive function in UML and you’ll notice the problem.
• A certain level of “OO-ness”: The existence of “Class diagrams” in UML reveals its intellectual heritage. But system architects shouldn’t think in terms of classes, which are like cells in a body. We must first decide if the body should have two arms or three, not the number of cells in each arm.
• Time to develop: Drawing diagrams takes time that could be used to actually write the code. This is particularly true of interfaces. A good Interface Control Document (ICD) and an interface definition are infinitely more valuable than a diagram. Once coding begins, diagrams are often discarded. Why were they created at all?

A multi-faceted approach to design seems more prudent. I prefer a combination of tables (for data definitions), sequence diagrams (for modeling interactions between systems), flow charts (for designing processes), schemas (for databases and XML formats) and natural language requirements. If done properly, the latter can be remarkably effective. Like a good specification, an effective natural language requirement should be:

• Correct
• Unambiguous
• Complete
• Consistent
• Verifable
• Modifable
• Traceable

Good specs and designs do not guarantee success. As in the entrepreneurial world, good plans do not make rich men. Execution matters.

Build the Organization
This is the most misunderstood diagram in software development:

Systems engineers design the systems that developers implement. Developers should not make judgments about how the user should behave. Likewise, systems engineers should not decide how to implement code. These competing interests need an arbitrator. In this diagram, I have called him an Integrated Product Team (IPT) lead after the Chrysler convention. Microsoft calls him a PM. Whatever his label, he knows enough about systems and software to mediate between the engineering factions. He also understands the business objectives, and can make the difficult distinction between too much schedule pressure, which harms analysis, and too much analysis, which leads to paralysis. He becomes the technical authority, the “System Solon”. Most importantly, he is at the top of the triangle. If software engineering dominates, then cross-cutting attributes such as performance may not be properly evaluated. If systems engineering sets the project tone, then code-level technical insights–“bottom-up” analysis–may be ignored. The Solon is the bulwark against both outcomes.