Is Up-Front Design Sufficient to Avoid Large Refactorings Later?

As it turns out, detailed up-front design can actually be supplemented rather well with test-first design (in fact, as we mentioned in Chapter 3, Doug proposed this on OTUG ^[12] about 5 years ago and was summarily rebuffed by the Extremos, so we re making the case again in this book). The resultant combination essentially means more up-front design and less of a dependency on unit testing ^[13] ”not to mention less pair programming and fewer integration issues.

In this section, we examine the Extremo attitude to up-front design and ask, can a detailed up-front design process, performed correctly, provide a good enough design to avoid large amounts of refactoring? (Hint: Yes.)

Is the Code Really the Design?

A mantra you often hear in XP circles is The code is the design! In other words, documentation is only a snapshot of the design ”a collection of instantly outdated assertions regarding how the program is constructed . The only really up-to-date reflection of the design could possibly be the source code because this is the manifestation of the design; therefore, it is the design. This is roughly equivalent to claiming that bricks , pipes, and conduits are actually blueprints because they are the manifestation of the blueprints.

This actually reveals an interesting division of thinking between Extremos and, well, non-Extremos. When most of us talk about design we are referring (albeit implicitly) to the design process, and when we talk about updating the design we are talking about updating the design documentation. Extremo philosophy, however, is that the design is inherent in whatever structure has been produced ”although it can t be touched, it s just there, like the ether . Therefore, the code is the design; therefore, because code is the end-product, anything besides code, such as design documentation, is optional.

Should we allow this piece of logic to dictate the amount of design documentation that we write and maintain? The following quote is from Alan Cooper (who has taken a relatively anti-XP stance in the past):

When the words are fuzzy, the programmers reflexively retreat to the most precise method of articulation available: source code. Although there is nothing more precise than code, there is also nothing more permanent or resistant to change. So the situation frequently crops up where nomenclature confusion causes programmers to begin coding prematurely, and that code becomes the de facto design, regardless of its appropriateness or correctness. ^[14]

Hmm . . . maybe the code really is the design. Of course, Cooper is actually describing what happens in a project with inadequate design documentation. If the documentation is no good, we have to rely on the code.

Light Bulb  

So the argument in XP that we should use the code as the design documentation because the documentation is no good is, frankly, circular.

We also quote Alan Cooper in Chapter 15 regarding Interaction Design (i.e., getting the product design right before coding ”a discipline that is sorely missing from XP).

 

Design documentation gives us something that source code can t: an abstraction of the design, a view from above rather than right down in the gutter . Simply asserting that the code is the design isn t enough. There are design idioms, intentions, and strategies that are all essential parts of design and architecture. The source code is just a snapshot of the architectural roadmap at any one time. It is completely lacking an extra dimension, which we would normally see captured in the architecture document.

We discuss design documentation in more detail in Chapter 7.

 

Is Up-Front Design Really a Bad Thing?

Up-front design is synonymous with thinking ahead.

We are not suggesting that the entire design for a large project should be carried out up front to the last detail, waterfall-style, but certainly a high-level technical architecture is essential to start with. Then (as the project is divided up into parallel teams and staged deliveries), more detailed (lower level) designs can be produced up front for each iteration.

Basically, the more up-front design, the better (well, at least until you have enough ), but there is a trade-off between the benefits and just making some progress with the coding. There is a cutoff point for design, a law of diminishing returns. However, due to its LackOfUpfrontDesign (LOUD), it is a point that XP falls way short of.

In his article XP Essentials: Emergent Design, Ron Jeffries writes :

There are many well-known modeling and design techniques that can be used to bring about a ˜good design . An incremental process may limit the applicability of these techniques, which are most powerful when applied and committed to ˜up front . ^[15]

When you take the time to think a design through and produce a class model, something special happens. The design becomes sane and well thought out, before any code has been written. It is well worth this relatively small investment in time, as the payoff is huge.

What are the benefits of doing an up-front design? Here are some, in no particular order:

• It provides design clarity.

• It provides a breathing space to let ideas gestate and develop before you risk getting bogged down in code.

• It is autodocumenting (the design is also the documentation). ^[16]

• Teams can move much faster because there is no dependent code yet.

• The interfaces are defined early on, which helps teams to work in parallel.

• Changing a class model is much easier than making the same change in code, because the class model is (or should be!) abstracted out to show only the detail that is relevant to the design.

• It makes subsequent changes easier (design diagrams give the team a high-level view of the design ”for example, a logical view that is separate from specific implementation details).

• Impact analysis is easier, because the design view gives the team a bigger picture of the dependencies between modules.

• It provides a reference point to make sure the code matches the design (i.e., an essential part of testing).

• It forms a contract. A contract sets expectations. You know when you ve finished. You know when you ll get paid. You know when it works.

Designing and programming are part of an iterative process. Even with the most well-realized and thought-out design, programming will reveal some areas where the design can be improved or needs to be changed. Thus, we need to go back to the design, make some changes, and then reflect the changes in the code.

More often than not, the process (having discovered a gap in the design) ends up being

1. Code the solution.

2. Update the design retrospectively.

This is partly why XP forgoes design and gets straight to the coding perhaps sooner than it should. The Extremos reasoning is that it takes longer to maintain a class model (or other design documentation) in addition to the code than simply maintaining the code.

This is a spurious argument, however, as it really doesn t take long to update the design in tandem with the code, especially given the round-trip capability of tools such as Together ControlCenter.

SOLUTION  

In much the same way that refactoring is a concurrent process in XP, keeping the design documentation up-to-date can also be treated as a concurrent process, albeit with significantly less overhead than refactoring (for starters, typically one person at a time can keep the design documentation up-to-date, whereas in XP the whole team must constantly refactor).

The benefits that you get from a design model also massively outweigh the small overhead involved in maintaining it, especially if you follow some of the Agile Modeling principles such as Model with a Purpose and Travel Light.

XP also forgoes up-front design on the basis that the design would be full of gaps anyway, and these are only revealed when you start coding. Sometimes this is the case, but as with many things in life, there are degrees of. In particular, the extent to which coding reveals gaps in the design depends on how much experience the designer has had with this type of project or the technology being used.

For many projects, the design will follow a well-trodden path . For example, J2EE projects use tried and tested design patterns and often become a paintbynumbers process. Web sites such as TheServerSide.com offer a multitude of best practice design patterns that you can pick off the virtual shelf and apply to your own design. With such projects, it is becoming increasingly rare that a new type of wheel needs to be invented every time.

Of course, this is not always the case. There is invariably some aspect of a project for which there is a paucity of prior experience. Just the amount varies. In such cases, testing and consolidating the design early through prototyping is essential.

How Much Up-Front Design Is Enough?

The criticism most often associated with up-front design is that the designers quickly get bogged down in design issues. This prevents the team from moving forward ”in other words, the team gets a nasty case of analysis paralysis. In fact, analysis paralysis (where the team is stuck in neutral, and no code is even in sight of being written) is a key sign that the team is doing too much up-front design.

So, how much up-front design is enough? Or, to put the question another way, what s the minimal amount of design that is sufficient to get it right while still avoiding analysis paralysis?

Doug has spent a large portion of the last 10 years answering this very question, and he has taken the trouble to write two books that focus on getting through analysis and design without catching a case of analysis paralysis. So we re going to borrow from that work here to answer this question.

Where XP is driven by stories, the ICONIX Process ^[17] is driven by scenarios (aka use cases). The difference starts there, because a properly written use-case scenario details both the normal and exceptional behavior of the system from the user s perspective. XPers leap into coding for the sunny-day scenario with loud cries of being test driven because they re writing unit tests for the methods they need right now while they re coding the simplest thing that can possibly work. In XP it s the customer who gets to worry about the rainy-day scenarios. In the ICONIX Process, the development team needs to take responsibility for making sure that some exceptional bit of behavior doesn t break the system. This is a huge difference.

One of the issues with design (either up-front or leap-ahead) is that it s tempting to allocate behaviors to objects (classes) before the objects have been identified. Doing so can (and often does) lead to analysis paralysis, as making these decisions can require careful thought. If the decisions aren t made with careful thought, the result is a bad factoring (allocation of operations to classes) of the design, and the result of this is Constant Refactoring After Programming. The irony is that in leaping ahead to behavior allocation, the intention would obviously have been to get a head start ”to go straight to detailed design (or coding in XP) and identify objects as you go along. Of course, XP adds fuel to the fire by encouraging this approach.

Simply doing some preliminary design work (domain modeling, robustness analysis) is very effective for identifying pretty much all of the objects that the system will use.

So that tells us how to recognize when to do more up-front design (in this case, preliminary design) to save time and avoid analysis paralysis. This also gives us the vital clue as to how to know when we have done enough up-front design. The answer is that we ve identified all the classes and all the important methods on each class.

In the ICONIX Process, the Critical Design Review (CDR) stage tells us whether or not the design is complete:

Before you commence CDR, you need to make sure that you have sequence diagrams for all of the use cases for which you re going to deliver code in the current release.You can t be sure that you ve found all of the responsibilities for each of your objects unless you ve drawn sequence diagrams for all of your basic courses and all of your alternate courses for all of your use cases. Taken together, these diagrams form the core of your dynamic model, which should now show the behavior of your system at runtime, including how the system will accomplish that behavior, in great detail. ^[18]

This is, of course, a serious amount of design detail, but we re talking here about the final part of the design in a process that streamlines the path from use cases to detailed design and concentrates on getting the design right. Effectively getting this amount of up-front thought in the design, and having that design reviewed by the senior developers before code, saves huge amounts of timeconsuming refactoring after you ve started coding for this iteration.

The key is to know what parts of the design to concentrate on in detail and, more important, which parts can be safely economized on, so that you aren t storing up trouble for later.

The book Agile Modeling also offers useful guidance on the subject, for example (describing the Agile Modeling [AM] core principle Model with a Purpose ):

If you cannot identify why and for whom you are creating a model, then why are you bothering to work on it at all? Many developers worry about whether their artifacts ”such as models, source code, or documents ”are detailed enough or if they are too detailed, or similarly if they are sufficiently accurate. What they re not doing is stepping back and asking why they re creating the artifact in the first place and whom are they creating it for. ^[19]

We provide more advice on the subject in the section Use Up-Front Design to Enhance Agility in Chapter 13.

 

^[12] Rational s Object Technology User Group , http://www.rational.com/support/usergroups/rose/otug.jsp.

^[13] Note, that does not mean less unit testing ”we just rely on them less!

^[14] Alan Cooper, The Inmates Are Running the Asylum: Why High Tech Products Drive Us Crazy and How to Restore the Sanity (Indianapolis, IN: Sams Publishing, 1999), p. 186.

^[15] Ron Jeffries, Essential XP: Emergent Design, http://www. xprogramming .com/xpmag/expEmergentDesign.htm, October 21, 2001.

^[16] This is also an XP practice ”the source is self-documenting , so design = source code = documentation. When all you ve got is a hammer . . . .

^[17] Doug Rosenberg and Kendall Scott, Use Case Driven Object Modeling with UML: A Practical Approach (New York, NY: Addison-Wesley, 1999).

^[18] Doug Rosenberg and Kendall Scott, Applying Use Case Driven Object Modeling With UML (New York, NY: Addison-Wesley, 2001), p. 108.

^[19] Scott W. Ambler, Agile Modeling: Effective Practices for eXtreme Programming and the Unified Process (New York, NY: John Wiley & Sons, 2002), p. 31.