2005-09-01 #1

“I Do Not Think that Word Means What You Think it Means”

One of my co-workers is a big fan of Joel on Software — and for good reason. Joel often has some really insightful and well-written articles. For example, I really enjoyed his article on learning to see problems in code. He nicely articulates some really good ideas, and really put a finger on something that has long bothered me about Exceptions.

So it was with some surprise that I read his stance on Big Design Up-Front (in my experience with the common parlance of Intelliware, I think we tend to say Big Up-Front Design — I don’t know how the word reordering happened).

Anyway, Joel says:

&#8220

I can’t tell you how strongly I believe in Big Design Up Front, which the proponents of Extreme Programming consider anathema. I have consistently saved time and made better products by using BDUF and I?m proud to use it, no matter what the XP fanatics claim. They’re just wrong on this point and I can’t be any clearer than that.

&#8221

My first reaction was to be surprised. Here’s someone that I respect a great deal saying the opposite of something that I believed, rather strongly. More than that, saying that I, like XP and other agile folk, am just wrong on that point.

So, I decided to read his “Big Design”. He makes a PDF version of his Project Aardvark Functional Specification available as a download. And as I read it over, I suddenly realized that Joel uses the term “Big Design” very differently than I use it.

Here are two examples of Design Documents I have received in my career.

The first comes from a project I did in the banking industry several years ago. It was a design for a COBOL batch program. The design document told me the names of all the modules that I was required to write out. Each module was accompanied by pseudo-code, big tables telling me exactly which data values I was going to receive from another programmer’s batch process, and the file format of the intermediate files. An application designer had spent several weeks producing this design, and there were several rounds of design reviews amongst all the senior team members.

When I started programming to the specification, it was quickly clear to me that the specification was flawed in ways that were immediately obvious once you actually started writing the code, but which weren’t as obvious on paper. I went back to the designer and encouraged a large number of significant changes to the design. And to a very large extent, I found myself wondering about the value of that original document that took so long to create in the first place.

In the second example, I was working on a C++ project for a now-defunct operating system (ah, OS/2, I still have a soft spot for you). Things were very different on this project: I wasn’t working in the dark ages of COBOL and mainframes and batch jobs. Now we were dealing with spiffy new technologies like PCs, and Object Oriented Design. But y’know what: it was the same story. I’d receive big class diagrams (we used Rational Rose in the days when it used Booch cloud notation) and sequence diagrams that a team of architects produced and I also had to refer to the big database logical and physical design models as well. There were reams of design documentation dealing with any number of topics.

But y’know what: all those design materials were flawed in exactly the same way that the COBOL design documents were flawed. Ideas that looked right on paper had glaringly obvious mistakes that were easily apparent once someone started trying to turn the pictures into code. And yet our project had several people whose sole responsibilities were to produce these types of artifacts for the project.

That, in my mind, is Big Design Up Front. And let me be very clear about one thing: this is not something that used to happen way in the past. This kind of Design process is still the norm in a lot of organizations.

Here are some of the features of Big Design, according to the C2 Wiki:

Formality. Big Design methods are decidedly not willy-nilly in their approach to software development.

Very high percentages of design-time (versus code-time) compared to the length of the release cycle, e.g. 30% or more, usually placed right at the beginning of the cycle.

A distinct design phase that is intended to capture all major decisions and most minor ones before any coding begins.

A system of responsibilities that tends to separate thinkers or planners of various sorts from doers or implementors, e.g. Architect vs. Coder.

Extreme attention to vocabulary, removal or clarity of all ambiguities, as if the natural language discourse associated with the above was a form of code, telling people what to do.

But, interestingly, that’s not what Joel seems to mean when he talks about Big Design Up Front. As I read through his Functional Specification, I didn’t see anything that I objected to. In fact, I could easily see myself producing much of the same material.

His 20 pages don’t really seem to play the role of a “design” in the sense that I was used to. If I were to characterize those pages, I’d categorize them as follows:

Purpose

Pages

Title Page

1

Table of Contents

0.5

Explanation about his Idea of Big Design Up Front

1

Overview

1

High-Level Architecture (including the web site flow chart)

3

Coding Conventions

1.5

User experience and future features

2

Descriptions of specific behaviour

10

The High-Level Architecture is comparable to what I’d think of as an Architecture Seed — a brief overview of the big pieces of the application and how they all fit together.

Coding conventions are a standard practice in agile methodologies, and I have a standard coding conventions document that’s considerably longer than the one that Joel provides. And even Joel admits that the coding conventions don’t really belong in a “design” document.

Finally, the last 10 pages contain descriptions of how the application should behave. “The application should show a screen that looks kinda like this” or “I need the following things to be logged so I can check them later”. This material is not unlike stuff we’d tend to write down on a story card during the story-writing process.

What the document doesn’t contain is big, elaborate object models, or entity-relationship diagrams, or pseudo-code, or anything like that. More often than not, the document talks about how the end-result appears to the outside world, and says very little about what the internal pieces look like.

So I’m left wondering: if this is the stuff that Joel on Software passionately defends, then why does he feel that he’s in such conflict with XP people? I don’t feel like I have a good answer for that.