Re: PHP and Diagram Tool

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@xxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxxx
2 Tees Close, Witham, Essex.
Gravity beer in Essex <http://www.eminent.demon.co.uk>
.

Relevant Pages

  • Re: TDD: Test-Driven Design or Test-Driven Development?
    ... >> how to improve the code to express their intent. ... >ancillary documentation? ... >> diagrams they drew. ... >> UML instead of expressing themselves in code. ...
    (comp.object)
  • Re: Why is Delphi more RAD than C++ ?
    ... question your preference not to use UML - like you say, ... class diagram I had just done and realized there was a class in my ... plain useless. ... documentation for them. ...
    (borland.public.delphi.non-technical)
  • Re: Q: Solutions for requirements tracing (to design, code, and test items)
    ... This is the way translation tools like PathMATE handle documentation. ... If you are doing UML models for the design, most drawing tools allow the application of such tags to model elements fairly painlessly. ... Now that OMG is standardizing tools through MDA, most UML drawing tools offer an XMI or equivalent access to the tool repository to extract the tags and their association with model elements. ...
    (comp.object)
  • Re: History of UML diagrams UML 1.0 to UML 2.0
    ... >> I am looking for documentation on the diagrams of UML. ... > The third edition is updated for 2.0, and describes what has changed over the years. ...
    (comp.object)
  • Re: Documenting Large Prolog Systems
    ... I have documented large Prolog systems, and it is not too hard. ... any of the off-the-shelf documentation tools like UML will be tortured if you ... document the main predicates -- not the helpers which are only there to ... Something like UML, ...
    (comp.lang.prolog)