[Tutor] Best practice for generalizing and documenting each method's behaviour

[Alan Gauld]

On 30/08/13 19:10, Bao Niu wrote:

> ... However, when there are many of such classes, exactly
> at what point to invoke check and clean behaviour becomes a little
> blurred.

I'm not too sure what you mean by that. Can you give an example?

> There is a desperate need for generalizing and documenting the
> behaviour of each such class, preferably in a flowchart. I'm currently
> doing the flowchart manually but the job becomes a bit overwhelming.

Apart from documenting high level processes or very low level code I'd 
not recommend a flowchart for anything much. UML Activity diagrams are a 
similar but much more powerful option. But even then I'm not sure I'd 
use them in the way you seem to be suggesting?

> I wonder what Python pros are using for analyzing and documenting
> classes/functions behaviours and interactions? Is UML the only way?

No there are many options. The simplest is probably CRC cards. And they 
can be turned into UML later if need be. Other OO methodologies exist 
too, but they are generally variations on the UML notation more than 
anything.

> Personally I found UML is a bit overkill for a one person project

You are not supposed to use all of UML on every project. For example in 
my work as an "Enterprise Architect" I use UML extensively but very 
rarely draw a class diagram and never draw object diagrams. But I use 
Use Case diagrams, Activity Diagrams, Sequence Charts and Deployment 
Diagrams in almost every project... But as a programmer I mainly use 
Class Diagrams, Object Diagrams, State Charts and Activity Diagrams.
On a small project just a Class diagram and a few Object interaction 
diagrams (or sequence charts if you prefer) would do.

The main thing to remember is that design documentation is primarily for 
the people who come after. You are trying to tell these future workers 
(who may be yourself) what you did to make it work. Too many people fall 
into the trap of trying to write design documents that
tell the current developers how to do their job - that's not usually 
necessary, they are probably the folks writing the documents!

-- 
Alan G
Author of the Learn to Program web site
http://www.alan-g.me.uk/