A design problem I met again and again.

[Martin P. Hellwig]

一首诗 wrote:
<cut>
> But I think the first step to resolve a problem is to describe it.  In
> that way, I might find the answer myself
<cut>
That is an excellent approach, knowing you have a problem and describing 
it is actually the hardest part of a design, the rest is more like a puzzle.

What I guess so far is that you tried to (re)design your work by 
grouping on functionality and using classes for more clearer work.
 From what you wrote (that is if I understood you correctly), both of 
these approaches don't really seem to get 'there'.

It might be worth to try another approach, instead of focussing on the 
characteristics of the functions and using them as a guideline for your 
design you could try this:

Step 1:
Write a Functional Design from a user perspective, restrain yourself 
from implying anything technical or choosing specific tools. Imagine 
yourself as an end-user and not as a developer.

Pick a random person of the street that looks literate but is not 
working in IT (secretaries are usually great for this!), let them 
comment on your language and then quiz them about the content to see if 
they actually understood what you wrote.

If commenting on language seems strange, in my experience if I can't 
properly describe what I want to say then there is a good chance that I 
haven't thought about it sufficiently or I was lazy in describing it.


Step 2:
Take this functional design and write a functional specification.
This is much like the design but instead focusses on the business 
processes and interdependencies of these. Write out implied constraints 
and things you might think is obvious, although the specification are 
technical in nature you should still avoid naming specific tools unless 
it is to describe functionality, i.e. google like approach of indexing 
data. Use plain English (or whatever language you want to write it in) 
for this, don't use any diagrams, SQL table layouts, UML etc.

Pick a random IT related colleague (network administrators are usually 
my preferred choice), let them read it and quiz them to make sure the 
specification are clear enough.


Step 3:
When you have your functional specification, write a technical design.
Here you make a choice on the tools you are going to use based on 
evidence based research and describe the general outline of your solution.

Pour your co-worker a nice cup of beverage of their choice and let them 
read it and of course quiz them.

Step 4:
Finally, use the technical design for writing a technical specification. 
Design you program using UML (or whatever thing that makes you look like 
you are developing without writing code). Specify deep, down to the name 
of all 'public' functions.

Step 5:
Let it rest for the weekend.

Step 6:
Reread your technical specification, if it still makes sense, continue. 
If it doesn't, go back to step 1 and repeat the process with the changes 
you made.

Step 7:
Do what you usually do (I write my unit-tests first and then solve them).

Step 8:
Compare the end product with your original functional design.
If they do not align go back to Step 1.


Some hints I found useful during step 4. I try to take in account that 
it is not me who is going to develop it but a team of reasonable 
qualified developers. Thus I split up the work in parts that can be 
simultaneously done by more then one person without them needing to know 
exactly what the other one is doing. If there is a need to know what the 
other developer is doing then the specification was not precise enough.

If during the whole process something comes up that shows a better way, 
change your documentation accordingly.


When all of this still results in an 'ugly' design, try letting more 
people read your documentation, if that doesn't help then one or more of 
the following may apply:
- Despite of its ugliness it is the most elegant design possible.
- You are working on something that is fundamentally broken.
- You haven't met the person that can give you more insight.

YMMV
-- 
mph