PHP and Diagram Tool

**Colin McKinnon** · Dec 16 '06, 03:55 PM

Re: PHP and Diagram Tool

Flak wrote:

>
I am a beginning to intermediate PHP programmer. Home schooled. My
programmes are starting to get rather big with a couple of thousand
lines of code and 10's of different files. I am starting to lose the
bigger picture.
>
I want to start using a flow/diagram tool. But I have no idea what
program to use. Are there experienced users that can help me with this
subject? What to look for in a program and what to not look for.
>

One that works on your architecture would be a good start. One which *you*
find effective and easy to use.

UML (a diagramming system - not a specific bit of software) is pretty much a
defacto standard for OO design...but you use the word 'flow' in your
request - does anybody still use flow diagrams? It rather suggests your
coding style is sloppy.

If you are not already using PHPDoc (or similar) then its definitely time to
learn.

HTH

C.

**seaside** · Dec 17 '06, 12:05 AM

Re: PHP and Diagram Tool

Colin McKinnon schrieb:

Flak wrote:

I want to start using a flow/diagram tool. But I have no idea what
program to use. Are there experienced users that can help me with this
subject? What to look for in a program and what to not look for.

>
One that works on your architecture would be a good start. One which *you*
find effective and easy to use.
>
UML (a diagramming system - not a specific bit of software) is pretty much a
defacto standard for OO design...but you use the word 'flow' in your
request - does anybody still use flow diagrams? It rather suggests your
coding style is sloppy.

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.

Flak, in case you want to start learning UML, you might wish to
download Visual Paradigm for UML here

Visual Paradigm - AI-Powered Visual Modeling

http://www.visual-paradigm.com/product/vpuml/

Design, analyze, and manage complex systems with the world's leading modeling platform.

Search there for 'Community edition', which is free and available for
Mac OS X, Windows and Linux.

**Peter Fox** · Dec 17 '06, 03:55 AM

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@eminen t.demon.co.uk.n ot.this.bit.no. html
2 Tees Close, Witham, Essex.
Gravity beer in Essex <http://www.eminent.dem on.co.uk>

**Rik** · Dec 17 '06, 04:15 AM

Re: PHP and Diagram Tool

Peter Fox wrote:

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*.

Putting myself on the the position of a user I want both: A comprehensive
diagram of overall flow, and a user guide which explains all possibilities
in detail. An overall overview really helps understanding, 'a picture is
worth more then a thousand words' still applies.

Offcourse, it all depends on how much of the flow the users should be aware
about to use it. It's one off those rare occasions in miss M$ however. M$
Visio was apt to my need, but I'm not going to pay for it. It's the free
graphic programs I use now to clear up certain dependancies, but they're
not very user-friendly.
--
Rik Wasmus

**frothpoker** · Dec 18 '06, 01:55 PM

Re: PHP and Diagram Tool

I want to start using a flow/diagram tool.

Do you mean you need to document the existing process flows, in which
case any flow charting system will suffice (you could even do it in
Excel / Word using the wordart shapes) or do you mean to re-engineer
the code into something like the MVC model where you separate out
business logic from data access and user interface, in which case
something like Code Igniter or Ruby on Rails would be worth
investigating.

or do you just mean some sort of source code control so you can see
what it in your live systems and what is in development code.