Best practice for generalizing and documenting each method's behaviour

[Steven D'Aprano]

On Fri, 30 Aug 2013 11:04:28 -0700, niubao56 wrote:

> I'm starting a small project coding in Python as I learn the ropes. As
> the project grows bigger, there are more and more overlapping and even
> redundant methods. For example, several classes have a
> checkAndClean_obj_state() method. If just one or two such classes, it is
> easy to analyze the behaviour of them and design the optimal interaction
> for all objects. However, when there are many of such classes, exactly
> at what point to invoke check and clean behaviour becomes a little
> blurred. 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.

If you are suffering from UML burnout in a *small* project, as you say 
you are working on, then I suspect your program design may be suffering 
from excessive use of classes and Java-itis. Ravioli code is just as bad 
as spaghetti code.

What do you consider "small"?

As far as I am concerned, if it is not *absolutely obvious* at what point 
to invoke check and clean behaviour, then the chances are very high that 
this checkAndClean_obj_state method either does too much, or what it does 
is poorly thought out. For example:

* Why do you not check and clean the object at creation time?

* Why does one method do both "check" and "clean"?

* Once it is checked, how is it possible that it becomes unchecked?

* And similarly for cleaned?

* Is your code controlling a nuclear reactor? If not, then maybe you 
don't actually have to call checkAndClean_obj_state before *every* 
operation, just call it once at creation time and let the chips fall 
where they may. The Python philosophy is that we're all adults here, and 
you can't stop somebody from shooting themselves in the foot.


As for your desperate need to generalise the behaviour of each class, 
don't fall prey to the temptation to over-generalization. Every time you 
think of generalizing something, say to yourself "YAGNI" (You Ain't Gonna 
Need It). You must be your own harshest critic, and demand real benefit 
before generalizing a class, not just "it might be useful some day".

You can always generalize and refactor next month.

Regarding documentation, I never find writing documentation a problem, 
because I nearly always write the documentation *before* the code. How 
else do I know what the code is supposed to do if I haven't written it 
down first? I cannot tell you how many times I've discarded what seemed 
like a good API in my head, because *writing it down* showed me that it 
actually sucked.


> I wonder what Python pros are using for analyzing and documenting
> classes/functions behaviours and interactions? Is UML the only way?
> Personally I found UML is a bit overkill for a one person project, but
> I'm not sure if it is the right direction. I'd appreciate any insight.
> Many thanks.

http://drpaulcarter.blogspot.com.au/2009/03/uml-considered-harmful.html

http://c2.com/cgi/wiki?UmlConsideredHarmful

And the perspective of a TDD/XP zealot:

http://c2.com/cgi/wiki?UmlDoesntWorkForDesign


Personally, I like English. I prefer to document my code in English, not 
jargon. UML is a language, but it is a jargon language, and while I'm 
sure that some people like it, I do not. I can never remember what all 
the dots and circles and arrows mean. If I was working on a giant project 
with 80 other people and millions of lines of code, perhaps it would be 
worth learning UML for parts of the design. But for a one-man project 
with only thousands of lines of code? I doubt it.


-- 
Steven