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.
