Writing partial designs

I recently kicked off a piece of development work and then handed over leadership of the small team to someone else. The new leader is keen and thorough, but I don't think I've really persuaded the rest of the team of the value of writing down partial, incomplete designs.

The developers in the team seem to have the impression that doing design involves solving all the problems and then writing up a solution. But it's much better, as I've mentioned before, to use a design document as a work in progress which records the solution so far and has placeholders for all the known problems. Such a 'live' document can be shared with other people and used to stimulate new ideas and solutions.

Rock climbing provides a good analogy. A team can climb up a rock face without pausing to bang in pegs. But then one person's achievement in reaching a particular point of the climb can't be shared by those following behind. Also the effects of a fall can be catastrophic.



In a similar way, writing down partial designs enables a team to build on each other's progress. If a major design problem turns up, it is often possible to reconstruct a solution from the remains.

This sharing of design information can be done verbally, but this lacks the precision of a written document and doesn't force out so many issues.

Silly Java rules?

Kevin Barnes observes that some pretty silly rules have developed around the use of Java.

I should declare my interest at this point: I work on Java standards and IBM's Java runtimes. That said, I think some rules of thumb are useful for beginners provided that skilled programmers break the rules as necessary.

I dislike classes with numerous getter and setter methods as this is a pretty strong hint that a class is badly designed, or that the programmer would have preferred a C struct ;-). Some consider these methods inherently evil, but I wouldn't go that far.

The use of final is more interesting. In C++, const is useful in defining good interfaces and final may play a similar role in Java. But the use of final on local declarations doesn't seem to be worth the syntactic clutter.

One of the proponents (thanks for the link, Kevin) of the use of final seems more concerned about controlling subclassing. That's a more interesting point to argue as it comes back to good interface design. But I don't think there's a general rule - it depends on the circumstances. Anyone designing a Java interface needs to understand the trade-off.

Since Java enshrines 'non-final' as the default (and it's too late to change that!), beginners risk coding Java interfaces that will behave unexpectedly when subclassed. But changing the language default wouldn't enable beginners to design good interfaces. As they say "there's no substitute for understanding".

Scrapping designs

When should you start writing down a design of a piece of software?

Some programmers put this off as long as possible. Once you commit yourself to paper, you start to become locked in to a particular direction. The more you write, the more you become wedded to a particular approach.

Others might advise skipping the design stage and getting on with coding. But the design lock in is even stronger once you have a swathe of code and a decent test suite. Refactoring is fun in small doses, but you'd have to be a masochist to want to spend a lot of time on it.

On the other hand, until I start writing down and organising my thoughts, I can't flush out most of the issues. Putting ideas on 'paper' forces me to define terms and helps me notice inconsistencies and omissions. Maybe I'm just a frustrated mathematician who can't solve a problem without a pencil in my hand?

No, seriously, writing a design down can be really helpful. Once you've done it, you can let the document go 'cold' for a while and then come back to it with a critical eye. It's hard to be objective when ideas are confined to your head. Also, dumping issues in a document helps me stop worrying about them - especially important when I'm trying to sleep.

The best compromise seems to be to start writing things down fairly early but to scrap a design and start again to free yourself from 'lock in'. If you use a decent version control system, you can always retrieve deleted versions.