Posted by Peter Fox on 12/17/06 03:40

Following on from seaside's message. . .
>While UML is definitely the best way to go, I wonder if Flak really
>would like to jump in here. UML isn't that simple at all.
No it isn't. UML is just one possibility.

It may well be that the OP wants more detailed documentation and a few
relationships in which case diagrams are _not_ the way to go at all.

UML is beloved of academics because they can 'teach it'. Many other
people think it's great because it is 'comprehensive'. IMHO diagrams
are for overviews and /illuminating/ other, more concrete documentation.
(Except back of envelope sketches which are (a) informal and (b)
scribbled in pencil in 10 seconds - unlike the hours of UML tedium.)

My opinion is this:
* You need pre-coding documentation
* You need in-code documentation (During development this will include
tags to loose ends such as '[T]' for deserves a test routine, '[D]' for
'needs to be mentioned in the user documentation'. For this you need
commenting standards and a program to interpret the standards.
* You need an object/routine/method/property summariser which scans code
to produce nitty-gritty documentation such as what sort of parameters
are required and whet the result will be...
* ... but you also need functional grouping of objects/methods to be
able to quickly navigate 'by feel' through code.
* IMPORTANTLY you need _briefing documentation_ that gives the
background to all sorts of matters inherent in your code or assumed by
the environment. For example how would someone twiddling with your code
(it could be you in a couple of years time!) access the database? Using
an object, set of objects, hierarchy of objects and what would be the
basic set-ups for those objects? Two ways are used here:-
1 - Comments and exercise code in the main code
2 - Stand alone example exerciser code.
I prefer method 2 as it is easier to split 'what it should do' from 'how
it works'.

All-in-all (even though I have a very visual style of learning) I would
rather spend the time others spend on pretty pictures, doing written
documentation and exercise code.

Put yourself in the position of a USER of a mass of code. An overview
diagram and outline of the principles behind the relationships would be
very useful - ie. where objects fit in the overall plan ... ... but
then you need to know what each object is about *in specific detail* and
*quickly*.





--
PETER FOX Not the same since the pancake business flopped
peterfox@eminent.demon.co.uk.not.this.bit.no.html
2 Tees Close, Witham, Essex.
Gravity beer in Essex <http://www.eminent.demon.co.uk>

[Back to original message]