Path: csiph.com!v102.xanadu-bbs.net!xanadu-bbs.net!feeder.erje.net!eu.feeder.erje.net!xlned.com!feeder5.xlned.com!newsfeed.xs4all.nl!newsfeed4.news.xs4all.nl!xs4all!newsgate.cistron.nl!newsgate.news.xs4all.nl!post.news.xs4all.nl!not-for-mail Return-Path: X-Original-To: python-list@python.org Delivered-To: python-list@mail.python.org X-Spam-Status: OK 0.013 X-Spam-Evidence: '*H*': 0.97; '*S*': 0.00; 'classes,': 0.05; 'preferably': 0.05; 'class,': 0.07; 'method.': 0.07; 'parsing': 0.09; 'subject:method': 0.09; 'cc:addr:python-list': 0.11; 'python': 0.11; 'project,': 0.12; 'objects.': 0.16; 'redundant': 0.16; 'wrote:': 0.18; 'looked': 0.18; 'all,': 0.19; 'bit': 0.19; 'thanks.': 0.20; 'written': 0.21; 'aug': 0.22; 'coding': 0.22; 'email addr:gmail.com>': 0.22; 'cc:addr:python.org': 0.22; 'cc:2**0': 0.24; 'cc:no real name:2**0': 0.24; "i've": 0.25; '>': 0.26; 'header:In-Reply-To:1': 0.27; 'point': 0.28; 'wonder': 0.29; 'message-id:@mail.gmail.com': 0.30; "i'm": 0.30; 'code': 0.31; 'documenting': 0.31; 'invoke': 0.31; 'way?': 0.31; 'becomes': 0.33; "i'd": 0.34; "can't": 0.35; 'classes': 0.35; 'tool': 0.35; 'but': 0.35; 'received:google.com': 0.35; 'there': 0.35; 'interaction': 0.36; 'doing': 0.36; 'example,': 0.37; 'two': 0.37; 'project': 0.37; 'starting': 0.37; 'problems': 0.38; 'little': 0.38; 'sure': 0.39; 'even': 0.60; 'read': 0.60; 'easy': 0.60; 'analyze': 0.60; 'manually': 0.60; 'such': 0.63; 'decided': 0.64; 'more': 0.64; 'to:addr:gmail.com': 0.65; 'due': 0.66; 'paper': 0.75; 'desperate': 0.84; 'subject:Best': 0.91; '2013': 0.98 DKIM-Signature: v=1; a=rsa-sha256; c=relaxed/relaxed; d=gmail.com; s=20120113; h=mime-version:in-reply-to:references:date:message-id:subject:from:to :cc:content-type; bh=vjsZOi5Mv7Nqvnn4gtHO4ZlaKS27A4ZVVV8D7AtfyOU=; b=hhW/gSRmTo+W2J0pbEtTVoofQnfuv9KPsx9NiWOONb/Amcuhh9cUbpVt2vyZqn2SLZ xkk5gL6Tqqbfo/AEWpvkDQ3dRKTgM2d9kRiho+T/XelD7aw+6Ep5npmRxv9/Hi6mNeve m7g6uZZHlH63keiptyiD5r45OrGFDCl+PiOUbCVN0HlRIM7LRdAO893wi8hU+YbE0KBH 21yciw1v5f7NjwjFE5a0mne1LAVYl/gAbpJjdW2q1nkS+3tH0FQoVhqw38glXSx2mAx+ HumELaJmbVbUT8+AeEfBS3oOICpZmg/oxWKn/F4vRrLnY1Dv+4q4l98UVht9ebUrPymk zhCA== MIME-Version: 1.0 X-Received: by 10.224.75.71 with SMTP id x7mr21167697qaj.30.1378002670950; Sat, 31 Aug 2013 19:31:10 -0700 (PDT) In-Reply-To: References: Date: Sun, 1 Sep 2013 03:31:10 +0100 Subject: Re: Best practice for generalizing and documenting each method's behaviour From: =?ISO-8859-1?Q?F=E1bio_Santos?= To: niubao56@gmail.com Content-Type: multipart/alternative; boundary=001a11c304b2b46da204e5493f2b Cc: python-list@python.org X-BeenThere: python-list@python.org X-Mailman-Version: 2.1.15 Precedence: list List-Id: General discussion list for the Python programming language List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Newsgroups: comp.lang.python Message-ID: Lines: 68 NNTP-Posting-Host: 2001:888:2000:d::a6 X-Trace: 1378002680 news.xs4all.nl 15871 [2001:888:2000:d::a6]:40141 X-Complaints-To: abuse@xs4all.nl Xref: csiph.com comp.lang.python:53395 --001a11c304b2b46da204e5493f2b Content-Type: text/plain; charset=ISO-8859-1 On 30 Aug 2013 19:07, 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. > > 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. I can't say I have ever used any tool for documenting python automatically. Human written documentation is always best. As for graphs and all, YMMV, but I've found that paper is best for expressing your code structure. I have looked into tools which generate graphs of your imports, but I found none of them satisfactory. There are a lot of problems parsing python due to its dynamic nature. In the end I decided to sit and read my codebase as I drew. --001a11c304b2b46da204e5493f2b Content-Type: text/html; charset=ISO-8859-1 Content-Transfer-Encoding: quoted-printable


On 30 Aug 2013 19:07, <niubao56@gm= ail.com> 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_s= tate() method. If just one or two such classes, it is easy to analyze the b= ehaviour of them and design the optimal interaction for all objects. Howeve= r, when there are many of such classes, exactly at what point to invoke che= ck and clean behaviour becomes a little blurred. There is a desperate need = for generalizing and documenting the behaviour of each such class, preferab= ly in a flowchart. I'm currently doing the flowchart manually but the j= ob becomes a bit overwhelming.
>
> I wonder what Python pros are using for analyzing and documenting clas= ses/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 sur= e if it is the right direction. I'd appreciate any insight. Many thanks= .

I can't say I have ever used any tool for documenting py= thon automatically. Human written documentation is always best.

As for graphs and all, YMMV, but I've found that paper i= s best for expressing your code structure. I have looked into tools which g= enerate graphs of your imports, but I found none of them satisfactory. Ther= e are a lot of problems parsing python due to its dynamic nature. In the en= d I decided to sit and read my codebase as I drew.

--001a11c304b2b46da204e5493f2b--