Measure Twice, Cut Once: Upstream Prerequisites

If you, dear reader, are reading this series because you (like me) are a computational designer who wants to learn some real top-notch programming skills to earn the big bucks by helping to push architecture and engineering out of the twentieth century, you might be wondering when this blog is going to actually display a single line of code.

bool timeForCoding = false;
if (timeForCoding)
{
    Console.WriteLine("finally!");
}
else
{
    Console.WriteLine("sorry bud, come back next week);
}

If you (like most of my current readership, come to think of it) are a designer or architect who is mildly curious about what sort of valuable lessons software development can teach us about turning a lot of complexity and risk into a wonderful thing that people love to use, then this week's post has a lot to offer. Chapter 3 of Code Complete is titled "Measure Twice, Cut Once: Upstream Prerequisites." As I still have metaphors on the brain from the last chapter, I'm picturing the construction of a water-powered sawmill—large logs floating downstream to be gathered up, carefully measured (twice!), and cut into useful timbers by skilled carpenters.

While lovely and romantic, this is not really all that useful a conceptual model for what Steve McConnell is talking about (see Ch.2 for how metaphors can lead us astray). Upstream prerequisites are all about planning, not tossing raw material into a river and hoping that the guy around the bend catches most of it. Before you start coding, you need to know where you're going, how you'll get there, and—most importantly—why you're doing it in the first place. Proper planning can make or break the success of a project, even before the first line of code is written.

In a nutshell: if you want a high-quality outcome for a complex project, you do actually have to plan for it. This is largely the value proposition of the entire Architecture industry. It seems to be a common trope that merely 2% of all homes built each year in the United States are actually designed by Architects. You should never really trust simplistic statistics like that, but it's clear that people who want to have a structure built for them believe that in most cases hiring an Architect is optional. That said, clients who demand an exceptional product for their money—a structure that will meet their every need and whim while also looking beautiful and functioning smoothly—know that the planning and conceptual design that Architects bring to the table is absolutely necessary. Perhaps it's the architect in me that finds this topic so interesting. All the planning and conceptual design that comes before the first foundations are laid—or even before the first plans and elevations are drawn—comprise an incredibly fascinating part of Architectural design. I think the same can be said of programming, though it's rarely seen that way.

"Upstream prerequisites" encompasses several software development activities in which the primary goal is risk reduction for the long period of construction that follows. When starting out on a programming project—any project, really—it's important to resist the urge to dive in and get started right away with producing. In a professional setting it can be even harder to resist, as the planning phases often leave few concrete markers of progress that you can show your boss. In Code Complete McConnell calls this the "WIMP syndrome" (Why Isn't Mary Programming?) and recounts an anecdote in which a team of 100+ software engineers working on requirements planning so thoroughly failed to impress a client during an office tour that they resorted to faking it by keeping code-like text prominently displayed on their screens. Part of every technical job is being prepared to educate others (usually people who pay you) in what you're doing and why it's important. This is one of the more frustrating tasks of computational design, which is a relatively young practice nested within otherwise ancient and convention-bound industries like architecture and engineering, but it's incredibly important because of how crucial this time is for the success of the project.

Another way of looking at things (or explaining them) is that it's important to do things in the right order. Errors and omissions at the beginning of a long process can lead to cumulative and compounding negative effects at later stages, with exponentially rising costs for fixing the damage. Starting at the very beginning, you should ask yourself what kind of software are you building? What is its scope? How important is it? Business systems have different requirements than mission-critical systems, which in turn have different requirements than embedded life-critical systems; a company intranet site is not developed in the same manner as avionics software for commercial aircraft. One favors an iterative, informal, and blended approach to planning and the other favors a sequential, formal, and highly scrutinized process. Computational design use cases mostly fall in the first category (increasingly the second), so looser, more iterative approaches to prerequisite planning are more common. Whichever approach you choose, it really pays off to spend some time getting everyone's head screwed on straight.

Of course, it's impossible to predict and plan for every contingency and detail ahead of time. McConnell advocates two targets: 1) For sequential development, try to define 80% of the project requirements and plan on periodic reviews to evaluate what is missing; 2) For iterative development, try to get the most important 20% of project requirements laid out and then proceed incrementally, with iterative cycles of development in which plenty of time is budgeted for additional planning and design.

Having chosen the rough approach, its important to start from the beginning and make sure—before all else—that we're focused on providing an answer for the right question. The first prerequisite to writing code is defining the actual problem. After that, we need to define the requirements for our solution—what criteria we need to meet in order to successfully solve the problem. Finally, we define the architecture of the solution—the high-level design of how we'll actually get there.

Problem Definition Prerequisite

The problem definition is essentially a mission statement, or a clear description of the vision for the project. It should define what the problem is without any attempt to solve it. Importantly, the problem definition must be presented from the user's perspective, without any technical jargon. After all, some problems don't actually require technical answers. We can save a lot of effort by identifying that early on. Problem definition is important because the cost for messing it up is double—we expend effort on solving the wrong problem as well as solving the right one (presuming you hit it on the second try). I wish I could say that there is a clear analogue to problem definition in architecture, because I think there should be. If you disagree, please leave a comment below.

Requirements Prerequisite

After the problem is clearly stated, we must explicitly define the criteria by which we will judge our success or failure. Requirements are important because they ensure that the user's needs are met in our quest to address the problem. There may also be other requirements that don't have anything to do with the problem definition, and these should definitely be called out ahead of time if possible. Well-defined requirements limit the scope of the coming efforts and prevent mission creep. In an ideal situation (which we have already stated is impossible) all the requirements would be defined at the outset and would remain perfectly stable throughout the rest of the project. In using a tool, the user often better understands her needs. It's natural that we adapt our desired functionality of a thing as we become more familiar with it. A child-sized butter knife and a Damascus steel chef's knife are from the same family of thing, but they are for two very different levels of user. In defining requirements, we should bear in mind that they probably will change and grow; we should prepare a process for ascertaining the cost of change and handling it gracefully. I liken the requirements prerequisite to the programming phase in architectural practice, in which everything the client states they need is considered and factored into choices made about the size, site, structure, orientation, and arrangement of spaces in a building before any building design even exists.

Architecture Prerequisite

Software architecture is analogous to the conceptual design phase in capital-A Architecture. Essentially, the effort and care put into software architecture ensures the conceptual integrity of the coming detailed design and construction phases. Much as architectural designers prepare evocative renderings, materials palettes, and descriptive 3D models of their designs in order to provide a visual framework and guide for the coming specs and BIM documentation, the software architect (ugh... sounds wrong to me) prepares a guiding framework for the programmers who must build the source code and test it. Here is where technical considerations come into play—where the more abstract problem and requirements start to meet the realities of writing computer language. While providing a clear structure that adheres to overall conceptual integrity, the architecture prerequisite must also partition work into manageable chunks so that work can be done concurrently and with a minimum of unnecessary overlap. Because software architecture is moving more into technical considerations, and since I want this post to be more theoretical in nature, I won't go into depth on all the necessary considerations of software architecture. If you're curious, you can see the main points below:

Despite having little to show for your effort at the end of the day, spending enough time on prerequisites pays off in the long run. McConnell references an internal study from IBM, in which the company determined that on an average project about 25% of the initial requirements got changed, which resulted in about 75% of the rework. Seasoned architectural readers will be all too familiar with those two dreaded words: "change order." You do not want to have to redo something important after its already in place. It's expensive and painful, and it's a guaranteed way to piss off those aforementioned non-technical people who pay you. McConnell advises software development teams to devote 10-20% of their effort and 20-30% of their schedule to prerequisites (and sometimes considerably more). Measure twice, cut once. It just makes sense.