Fog Creek Software
Discussion Board

Why this design spec/model obsession?

Hi. I work at a large european government agency and was dropped in the midst of a large and quite complex J2EE project about 7-8 months ago.

First of all I just want to say that I am not XP follower, although this subject and my standpoint may make it seem that way.

We have a large and complicated codebase, a really messy Rational Rose model, and quite a stack of design documents, all different and of varied quality. Me and two other guys have been appointed architects, and in this situation I am having a bit of a discrepance with one of the  other architects regarding the design model.

Our design model is at all times somehow expected to be an accurate representation of all the internal workings of the systems, having detailed diagrams for all use cases. So, if all the project members would die at once of some strange disease, the model would come to the rescue for our sucessors, being the means for them to assimilate all needed knowledge.

Now, I have seen this before, and it seems like nonsense to me. I agree that people should always design before they code.  I also think that all architectural mechanisms and commonly used pattern combinations in a project should be documented and followed. But at the individual use case level, I think that the design model should be disposable once written, unless you feel that you need to update it.

It should however not be a requisite for the design model to always be an accurate representation of the system. Because it is unavoidable that once your design is done, and you begin to code, entropy will rear its ugly head, due to deadlines, quick fixes, added functionality and so on. So why bother?
Why try to make the design model being the most accurate representation of the source code, rather than the source code itself? Why, why why? Why is source code so "bad" to look at?

Rather than waste time fighting the unavoidable, is it not better to spend time documenting the general design and documenting which classes implement certain functionality, making this a simpler way for eventual sucessors to know where to look in the source code when things go wrong?

To me, it seems like having an accurate design model (which is an utopia) is a lie, giving higher-ups in the corporate food chain a false sense of security ("What?  Fire old John? Why not, he's expendable, all his work is documented in the design model..").

And this without even considering all knowledge in the collective minds of the project members which rarely is documented. Design model, bah..

So, except from all XP people out there, am I the only one to have these blasphemous thoughts about "accurate" project design models?

Sunday, May 25, 2003

The design model is what the programmers look at. The use case is what the business look at.

If you don't care why the design model looks like it does, then by all means throw the use cases out. If, on the other hand, the requestors want a record of what the specifications where, and why things were done they way they were (CYA) then keep them.
Sunday, May 25, 2003

This isn't "XP:" it's called common sense, possessed by all experienced developers.

Sunday, May 25, 2003

"I agree that people should always design before they code."

I'm  not even sure I agree with that. Sometimes, the only to find out what you can really achieve is to just start trying ideas. If you INSIST on a plan ahead of time, that more or less disqualifies all kinds of interesting work and ideas.

Brad Wilson (
Sunday, May 25, 2003

I'm used to seeing reasonably thought out designs and a architecture on large projects, but not a formal design spec.  In fact, I always thought the real reason for a architecture was to provide guidance on how the design should change, when the requirements inevitably change or people discover mistakes later on.

The few times I've been on projects with true design spec's always involved big-ticket government projects with formal 'factory' and 'on-site' acceptance testing, and sometimes a third party like MITRE that provides technical expertise for the government representatives. Very different world.

Eric Moore
Sunday, May 25, 2003

Rational Rose, Yuk, Use Cases, yuk, UML blah, it's all nonsense backed by a huge marketing campaign in the late 90's.
Almost everybody has cottoned to the fact that it's all unusable. Why spend 10 days doing the sequence diagrams etc etc, when you can write the working code in 1?

Monday, May 26, 2003

Nice to hear that I am not the only one having the same thoughts about this subject then.

One question to Eric though: you mentioned that you also have been involved in large development projects such as the one I am working on, with the same focus on 'formal' stuff. You did however not mentioned the results of that, if it was useful, or just dead weight  (although I assume from your following post that you do not think higly of those things).

And Marktaw (is that your name?) rises a good point that the design model can be used for tracking business specifications. We do that. We have a use case case model supporting the business specs, and it is quite a good idea, as you can use them as contracts to analyze and validate  the business requirements specs documentation (as long as the customer can read use cases of course, which unfortunately has been an issue around here).

It is the posterior detailed design model I have issues with  (called Use case realization in RUP/UML universe). That is, the detailed design, with classes and interaction diagrams etc. That is the one that gets obsolete rather quickly as code evolvs.

Monday, May 26, 2003

Mark T. A. W. - they're my initials.

When you have a group of people as technology obtuse as most project requestors in large projects, especially ones with complex interactions, the more process you can wrap around the specification process, sometimes the better.

Also, hiring people to shield the developers from the requestors is often a good idea.

What documentation processes do you propose to replace UML/Rational Rose for this process? Especially a round trip process where the business can accept feedback on their requirements.
Monday, May 26, 2003

Not to mention the fact that on large projects, the requestors tend to be a committee or worse, a loose band of people with no official affiliation who all think they have a say in the process.
Monday, May 26, 2003

A rule we try to live by here (with props to Jim McCarthy):

"Never do anything stupid on purpose."

Basically, your quota of stupid moves is going to be filled by the things you do by accident. You do not have the luxury of doing stupid things on purpose.

If doing something like maintaining a perfect model is useful, right now, to the team, then by all means keep doing it. If it's not, you may be doing something stupid on purpose.

Only you can decide that.

Monday, May 26, 2003

Ultimately design is a good way of validating your implementation. In many places where implementation != design means bugs. Its a fine noble idea as long as you revise your design during implementation, or at the end. Early design is useful for producing test cases, but ultimately early design can only go into so much detail. Typically I like to keep the design isolated at the module level (internal module design is up to the developer) and interfaces between modules. Important areas like protocols & contracts are also useful to design early on.

But the rose-style of early overwhelming design is just not practical, and is impossible to truly revise properly. To make it work in any sense, you have to put your UML first & code second. Just doesn't work.

Often some places go for ultra heavy design for political reasons like ISO compliance and such, not because it makes any sense from a coding point of view

Monday, May 26, 2003

I'm still not sold on the "design on paper until you're blue in the face" mode of operation.

Last year I built an EDI processing/reporting engine.  My "design" was the database schema that I started working on week one. Now that the thing is in production and processing hundreds of documents a day, I look at the current schema on my wall and can still see the first tables I put down, and that design has served me very, very well.

We got bitten by a few business changes during integration, but I'm not convinced those changes would have come out in a formal design phase. In any event, it took me 2-3 days of coding to work around them, problem solved. Was that really worth spending 8-12 weeks on design?

I have a theory about design, which requires a minor digression:
When you have a bunch of data points that are in a rough line, there's an algorithm called "linear least squares" that will give you the slope and intercept of the line that is the best correlation to those points.
I read about a study that found that if you handed the average person a plot with points and a ruler, and asked them to draw a line, they would "eyeball" a line that was incredibly close to the linear least squares fit.

The conclusion being that our brain is capable of finding and identifying patterns, if you leave it alone to do so.

My theory on software design is that, with enough experience, a software developer can learn a problem domain and find the patterns naturally, *without* the reams of Rational product. Just from
a) Human experience
b) Development experience
c) Interviews with users - learning the area to be coded for

We can naturally find the appropriate patterns on which to model the software, and talented individuals will be 95% right. And I propose that no amount of analysis will ever find that last five percent.

So my heresy:
Why bother with any of it?

That's the part of XP that I definitely do like - when you're comfortable with being able to design, start designing. Modify the design as you go.


Monday, May 26, 2003

"Our design model is at all times somehow expected to be an accurate representation of all the internal workings of the systems, having detailed diagrams for all use cases."

I hope your group is using Rational's latest product called Rational XP? It seems to be only product Rational has that is capable of keeping the UML diagrams up-to-date with the source code.

"Why is source code so "bad" to look at?"

Looking at a little bit of source code isn't that bad. Looking at a lot typically is. Especially, when you are trying to patch or enhance code that was written by a group of people who moved on to bigger and better things a long time ago.

IMO, keeping accurate project design models throughout a project is possible but not practical.  Documenting after the fact seems to me to be the best way to accomplish this particular goal.

Designing before you code is another issue altogether. Big upfront design isn't necessary in all situations, but I certainly wouldn't want to do a large fix bid project without doing lots of analysis and design work first.

Monday, May 26, 2003

"In any event, it took me 2-3 days of coding to work around them, problem solved. Was that really worth spending 8-12 weeks on design?"

So that works for small projects. What if you were implementing Microsoft Excel? You have to coordinate with the other MS Office developers, and delivery a highly complex project with a team of hundreds (dozens? Joel help me out here) of developers.
Tuesday, May 27, 2003

How many small projects are there vs how many Microsoft Excels?

I'd say it's at least 1000 to 1.

And the horse you rode in on
Tuesday, May 27, 2003

In other words, I'm saying that Microsoft Excel's existance doesn't invalidate his point, because Excel is the exception, not the rule.

And the horse you rode in on
Tuesday, May 27, 2003

"In other words, I'm saying that Microsoft Excel's existance doesn't invalidate his point, because Excel is the exception, not the rule. "

Sure, I'm not saying that isn't true, but when someone complains about detailed project specifications because it takes 3 days to code something, I think they're missing the point of detailed project specifications... they're for detailed projects.

They're also for iteritive projects where version 1.0 is being coded concurrently with specifications being gathered for 1.1. I hope you don't expect the coders to be the ones gathering the requirements while they have a deliverable that's 2 months away and 3 legacy systems to integrate.

They're for multi-million dollar projects where the reputation of a company the size of a Microsoft or a Chase Manhattan Bank are at stake.

I worked in a highly beaurocratic environment on a complex multi million dollar system and while I think sometimes the project spec got in the way of clean coding & design, and therefore made things more difficult and take longer, I'm glad it was there all the same.

Any tool that can get 15 middle managers to agree on something is good, IMHO. And any tool that can also get those same 15 middle managers to look at the end product and say "Yeah, it does what we asked for it to do" is good.

For a project that takes one programmer 3 days to do, a simple meeting, e-mail/confirmation e-mail and some bar-napkin drawings are all the specification you need.
Tuesday, May 27, 2003

The problem with software is that we seem to 'engineer' everything as if its the first thing of that kind ever sighted on the planet. Compared to normal engineering where an engineer can look up a chart and say "we need 10 concrete poles to support 25 ton of concrete slab, each placed 10 feet apart", that's all they need to do.

Rational methodology tends to overcomplicate wheel reinvention. For example why write UML, use cases, object sequence diagrams etc, etc, when you are populating a grid with code -  description  combinations and allowing a user to edit the description.

In normal engineering practices the design document would read:
"allow the user to alter code descriptions according to industry standards"

We need to produce biblical dimension documentation to describe this sort of functionality.

Tuesday, May 27, 2003

Because there's more money in creating code from scratch than there is in creating 10' poles from scratch?

No construction company is going to become totally vertically integrated to the point where they harvest trees and turn them into 2x4's.

Buildings tend to be pretty generic. Programs, on the other hand... are less so. Besides, in VB, creating a button is really a matter of dragging & dropping. There's your 2x4.

I certainly get your point though. No architect is going to redefine the door. (though creating a use case for a door might be a funny/revealing exercise) Few architects would even bother to define the dimensions of the door - these things are pretty much standardized.

Then again, so are user interfaces... It's not like you're redefining the button each time you build an application.

Now here's a question for you. The New York Times commissioned a building in NY. It'll probably be the first skyscraper to be built since September 11, 2001, and it will be near the Port Authority.

How do you think the New York Times communicated to the Architect what their needs were? Do you actually believe specing out, designing, and the building a skyscraper is less sloppy & involved than creating a software product?
Tuesday, May 27, 2003

"Measure twice, cut once" is not a concept that isn't applicable to the development of a complex software system.

I do agree that the most common systems being developed today of the three to six month variety can be developed successfully with a less formalized process. However, we ran into MAJOR issues when attempting to use a "light" process with little "paper" detailed design.

Things worked out really well during the development of the straightforward aspects of the system. However, when things became complex, the major breakdowns started. The primary problem--since the design was not done on paper before coding, we got 1/2 way through the coding of a rather complex part of the system and realized that the solution wouldn't work because the design of the code wasn't thought out all the way through, hand-in-hand with the requirements.

Why? Because there was no design process performed before coding began.

Code had to be scrapped and "refactored."  This took 2 weeks and forced re-testing of all affected functionality, taking another week.  Had we thought through the entire design on paper, we would have gotten half way through and said, "Oops!  This won't work," and we would have changed a few lines of text in a Word doc instead of reworking a bunch of working (for the first half of the functionality) code, a much more complex task.

Now, what would have been better? Spending a day or two talking about what we were going to do and outlining the design on paper (or in a CASE tool)?  Or depending upon "refactoring" (AKA, ripping tested code apart and re-writing it because you didn't write it correctly the first time) to solve our issues?

Building complex software is no different than constructing an office building. You can't have the contractors all show up and start assembling the thing without the design thought all the way through first.

The bottom line for me is that you need to figure out how the system is going to work one way or another. What's easier to communicate and review among the team members? A diagram that shows interactions among classes or sitting down and stepping through the code? It's all about what's the easiest to get your brain around during the process of communicating.

Tuesday, May 27, 2003

Excel's a weird example.
Microsoft development techinques are definately not 'design everything first'.

Tuesday, May 27, 2003

There's a middle ground between plan nothing and
plan everything. As usual the middle path is hard
so we go to the extremes because it is explicable.

Whe you take a trip how do you do it? Do you plan
every turn of the wheel? Of course not. Why? Because
you are comfortable enough with your overall plan
to let the minute details of driving be spontaneous.

In projects there are such points too.

Much of project can be worked out through discussions,
much faster than writing code. In the discussions do we
need every class? Every method? Every line of code? No.
But we do need to get comfortable we are going in the
correct direction.

With mind simulation we can take many round trips
through the project, beginning to end, sideways and
out.  Most of the time this will prevent the killer problem
that shows up half way through a project. Even
more so the more familiar you are with a domain.

Of course you'll miss stuff. A crisis will pop up. But not
so many that can't be handled.

A mind is a terrible thing to waste. Thinking through
everything isn't  the same as specifying everything
in detail, which is impossible because the road keeps
changing as will your destination. But it's not hard
to figure out where you are going and how to get

Tuesday, May 27, 2003


The failure you mentioned wasn't caused by a failure to continually updated your design documents. It was caused because the team didn't *finish* the initial design on paper in the first place.

I see a lot of comparisons to construction here. The analogy between software development and the physical construction of buildings seems to work well  at first glance, however, it falls apart under a little scrutiny. In construction, the customer rarely makes capricious changes to the fundamental design in later stages of construction. The customer rarely insist on moving a bathroom to the second floor in the final week of construction.

However, in software, this happens all the time because the customer doesn't perceive or understand the cost involved. "Hey, we need to add support for <XYZ>. This isn't a problem is it?" Yeah, we've all been there.

In construction, an architect will have a detailed set of plans because he has a reasonable assumption that they are not going to change dramatically after construction begins.

How many of us have worked on large projects where things didn't change dramatically well into the project? That's what I thought...

On my projects, I do a complete design on paper first, I'll design my databases, classes, method names, etc. I make every effort to find problems or gotchas long before I code. I spent a great deal of time up front in trying to create a flexible, extensible design.

Then I start coding. When changes occur, I rarely update the initial design documents. Why? Because their purpose was to construct and prove a design, not serve as documentation.

If you want documentation, reverse engineer my code in Visio or other tools to get a UML diagram. Read my comments, examine the code.

If you have two sources of information about your project; one being the documentation, the other being the source code, then you are going to have a situation where invariably they get out of sync.

Mark Hoffman
Tuesday, May 27, 2003


I think we're on the same wavelength.  I was under the impression that the point of this thread was that creating an initial design is a waste of time, as opposed to keeping every little detail of the design up-to-date.

I agree with you wholeheartedly--that's the whole reason good modeling tools support both forward AND reverse code engineering (at least in theory, anyway--most don't handle this little feature too smoothly.)

So I agree--do your best to hash out the design up front, so you can come up with a model that will actually solve your problems, but remain limber and flexible and get the project done.

And by the way, there are ALWAYS changes in a construction project throughout its lifetime, so this analogy is quite valid.  We write software for the construction industry and you'll never guess what one of the big requirements is from our clients...

Tracking and billing for change requests.


Now, granted, the cost of a change request is sometimes quite high, depending upon the complexity.  Why?  Because the design needs to be updated and all designs that are affected need to be updated.  Now, if you just want to move a window in a two-story house, that's not a big deal.

I think it's all about the size of the change and the scope of impact. I don't think it's true that you can ALWAYS avoid updating the design; I think it depends upon the scope of the change.

Anyway, to do things "right" is always a pain in the butt, and oftentimes not worth the trade-off in time. It's all about finding the balance, as mentioned in a previous post above...

Tuesday, May 27, 2003

Building construction is sometimes done the 'fast track' method: construction starts before design is finished. And change requests of all sorts are quite common. And bugs in the final result no matter the methedology are also common. Thankfully, they're usually of the annoyance type, but there can be major usability problems and sometime structural ones. The relvance here is that they only come out in 'testing', sometimes not during design.

Here's a site on construction methedology. I haven't read it in detail, but check out the chart for the 'austin method'. Costing early but not all detailed design.

Tuesday, May 27, 2003

Tuesday, May 27, 2003

Nice to have so many interesting replies.

I just want to make clear, again, that I did not in any way meant to question up-front design activities on paper/Rose/Visio whatever before starting to code. That is common practice, although I think it it should be kept to a minimum whenever possible, resorting to commonly used and in the project architectural mechanisms (honoring the pragmatic programmers DRY principle).

What I wanted to discuss when starting this topic was the insanity of trying to keep detailed design models and specs for individual use cases up to date with the source code at all times, when we know that it takes too much effort, and that it instead should be wiser to spend that time documenting the general catalog of architectural mechanisms (ie design at a higher level), and simply keeping a map of the source code, regarding what code implements which functionality, so that when necessary, it should be quite simple to dig into the source code.

Summarizing, what I meant is that once the design is done and the code is written, simply do not bother updating it to reflect all changes in the source code. It takes too much effort, and takes away focus from the source code, where the ultimate truth always will be. As I said (and have heard somewhere before):  the best representation of the source code, is the source code.

Tuesday, May 27, 2003

Mark -
"In construction, the customer rarely makes capricious changes to the fundamental design in later stages of construction. The customer rarely insist on moving a bathroom to the second floor in the final week of construction."

I'm sorry, but I suspect the average building architect would be laughing their asses off right now. Absolutely there are changes once construction has started. I suspect the major reason buyers aren't allowed on a building site during construction isn't liability - it's "oh, can you move this over there?"
However, the thing that is wonderfully established in the construction industry is that design to the nth degree is a requirement, that it must be signed off by the purchaser, and changes cost MONEY.

Now, for fixed-price software contracts I am the #1 proponent of a detailed spec signed (yes, in ink) by the client. And changes cost money.

My argument is that to accomplish the job detailed design to the nth degree is NOT necessary, and is generally a waste of time. Design enough to know where you're going, then start down the road.

Here's another thought - when you're designing, there are going to be assumptions made. Let's say at some point you make an assumption that Datasets will be appropriate for the job, then you continue designing for another two weeks. You get to that point and find that [x] is NOT appropriate for the job. Now you have:
a) wasted two weeks of design
b) lost the time necessary to discover that datasets aren't workable
c) lost the time necessary to redesign the application around custom code instead of datasets

If you don't insist on a detailed to the nth level design spec, then you don't lose (a) and (c) - just (b), which was lost time anyway.

"Well that's why we prototype" you say? You prototype enough to avoid all the little traps and pitfalls and you've built the application.


Wednesday, May 28, 2003


I wasn't suggesting that the customer doesn't want changes during construction. I'm saying that because of the high costs involved, most major changes are covered upfront, when it's the cheapest to change.

It's not too often that the client approaches the builder 90% of the way through the project and says "Hey..I was thinking...instead of 2 stories, can we make this baby 9 stories?"

When major changes do occur, the customer is aware that it's gonna be *expensive*. In software, the customer is largely clueless about the additional development time and cost. "Whaddya mean it will add 10% to the timeline?!?! I just want XXXX!!"

We can keep pretending that the construction of buildings and the construction of software are perfectly analogous, but we are only going to keep hitting the same frustrations every time the customer insist on a major change late in development and doesn't understand why it can't be done over the weekend....

Mark Hoffman
Wednesday, May 28, 2003

Anyone tried the analogy?

Yes, you can have XXXX. It can't be done over the weekend just like you can't move your bathroom to the other side of the house in a weekend.

Thursday, May 29, 2003

*  Recent Topics

*  Fog Creek Home