[FRPythoneers] PythonDoc review

Sean Reifschneider jafo at tummy.com
Wed Mar 29 01:01:17 MST 2000

On Tue, Mar 28, 2000 at 10:15:11PM -0700, Charles Morrison wrote:
>Many thanks for this review. I certainly appreciate it.  I keep reminding
>myself to comment my  code, although it may be only for myself. I've had to

Well, there are comments and there are comments...  I like doc_strings
because they're easily extracted and can be used for helping to document
for reuse.  I mostly try to keep my code easily understood and comment
functional blocks to make the flow easiy to follow.  "If the code and
the comments disagree, probably both are wrong."

Everyone has their own requirements though.

My main reason in looking for another language than C was to increase my
code reusability.  Well, that and I was tired of using malloc for string
manipulation.  :-/

>Unfortunately, I tend to rely on simple comments way too often. This leads to
>lengthy relearning sessions where a simpler "broad view" approach would be

Hmm.  I tend to keep my comments very simple as well.  I usually limit code
comments to a single line for parts that are overly complex to understand
by a quick reading.  I document methods and modules well, but leave
comments terse.

One of the common problems with bug-fixing is that they are often made
without a full understand of the nuances of the code involved.  The only
way to ensure that doesn't happen is a thorough reading of the code
(not comments).

>but find that relying on certain symbols to represent complex relationships
>requires readers to learn UML (a separate language in itself). So we need to
>learn Yet another language to communicate about our logic? hmmm where does it

You know, I've never really been a fan of ERDs and flow charts and
all.  It's just never worked for me.  I can see their usefulness,
but the tools have always felt like they were just getting in the way.

>It would be nice to be able to do some things visually, but more to the point,

Well, I believe that's what Boa-Constructor is tring to do.  Unfortunately,
I was never able to get it running (I spent nearly 5 hours this
weekend on it).

>level of broad/detailed information available without unduly slowing down or
>distracting the programmer. Oh, and it has to be language independent as well.

You don't ask for much...

Do you have any ideas on solutions to your problems?

 People who interview themselves shouldn't criticize writing styles.
                 -- John Bentley, Programming Pearls
Sean Reifschneider, Inimitably Superfluous <jafo at tummy.com>
URL: <http://www.tummy.com/xvscan> HP-UX/Linux/FreeBSD/BSDOS scanning software.

More information about the FRPythoneers mailing list