How do you know how much design is too much?

Question

I am supposed to write "detailed" design documents for my job, but I always find myself overspecifying parts and getting burnt out when I realize I can't specify everything exactly in the doc or I would basically be writing the code all over again! Is there a good rule of thumb when it comes to writing design documents to help guide me to know how much is too much and how little is too little?

Answer 1

It depends on what's customary in your company. In my experience:

• Design documents save you most time at the beginning of the design process, i.e. when you are confused.
• The more you design, the less you are confused (you sort out problems, you ask clarifying questions, etc...)
• You reach a point in which it would take you less to do the design in code. It's the right moment to switch to development.

I.e. start developing when you know exactly how you are going to implement your stuff.

Answer 2

Your design should give you the high level structure that lets you dive into code and sort out the low level details.

If you are thinking about high level structure whilst writing the code then its time step away and go back to the whiteboard. Equally if you find yourself adding detail just to make the diagram look complete then its time to start coding.

There's always the temptation to overly refine the design just to make it look good. But the best way to validate an uncertain design is to try it out in code. Most importantly remember you can jump back and forward between then two iteratively, rather than force yourself to try and get everything right first time.

Answer 3

If you don't know the main players in your design, you haven't gone far enough.

If you know public method and property names and purposes on the main players, you're probably about right.

If you know private methods and properties, you went too far.

Of course, there will be one or two special cases where you need a little more detail like you may need to specify the type of algorithm used for a sort or search, for example.

This is very subjective though. You should design until all major risk is mitigated and you feel comfortable in starting to code a solution. But always remember that design is iterative, it's not a once only task.

Answer 4

I like to draw parallels between software and general engineering, and it seems fairly obvious that code itself is analogous to blueprints. Engineering also makes use of design documents, but they are generally high-level enough that they don't include the kind of information you would expect to find in a blueprint.

So if your design document is specifying things like classes and methods and parameters and table columns and so forth, then it is too low-level. If you find yourself typing stuff that you should be typing into your IDE, then it shouldn't be in your design document.

This is theoretical, however. The real rule is that you have to write documentation until your boss says it's enough.

Answer 5

The only rule of thumb I have verified is: the most time you spend on detailed design, the more the design will change once you get down to code. But I know that is not helpful =),

One heuristic I would use is:

• Once you find yourself trying to describe complete classes with every method and attribute you believe it should have (compared with specifying them just at the conceptual level with the name, responsibility and one or two of the principal methods), you are over-designing.

Answer 6

This is a difficult question to answer as it very dependent upon the organisation and the project.

If you have many developers working on the project and work needs dividing between them, then I would say the design needs to define the rough functional areas of the system and the primary contracts between those areas.

This could be achieved by formal documentation or by more pragmatic techniques like tracer bullet development.

If you need to write a document for other developers or for review by other members of the team e.g. architects or analysts then I would say keep it simple. Show the overall decomposition of the system, the important features of the architecture, e.g. distributed, web application etc but leave out a lot of the detail.

This can be added later if needed for clarification by the team or naturally discovered as part of the development. However try to ensure that there is enough detail to capture the important aspects which wouldn't be obvious from looking at the code.

Answer 7

1. Requirements. Do you have a good requirements doc, or at least a reasonable one? If not, start there. Sketch out the general requirements for the system.

2. Use models. Define the use models -- what the things are that users will manipulate and how they will manipulate them. Compare with requirements. This may be an iterative process between identifying requirements and defining use models.

3. Objects. Identify the objects necessary to implement the use model(s).

4. Object relationships. Identify the relationships between the use model objects. Define other "helper" objects necessary to glue everything together. Maybe even sketch out a UML diagram to make the whole thing a bit more concrete. I don't necessarily recommend a full system UMLdiagram, building that can be a bit onerous. However, one that shows the key objects and their relationships is important.

5. Now you can go to classes or modules, depending on the language you are coding in. At this point you are treading the thin line between designing and coding. However, a little detail at this point can help you validate the design work you've done so far.

The main point is that the planning is more important than the plan. You need to go through this excercise to build a mental model you can reason about. The written text and diagrams may be less important -- unless your manager requires them .

Answer 8

Interesting reading on the subject.

Take a look at it when you have time.

http://martinfowler.com/articles/designDead.html