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 -- http://mail.python.org/mailman/listinfo/python-list
