[FRPythoneers] PythonDoc review

Charles Morrison cmorrison at info2000.net
Tue Mar 28 22:15:11 MST 2000


On Mon, 27 Mar 2000, you wrote:
lots snipped...

> I'm left wondering why these tools aren't a higher priority.  Does no one
> really use javadoc?  Could it be that once I have the tool I'll find I
> don't use it as much as I expect?  Building reusable code would seem to
> dictate it as a requirement, users won't likely be "fresh" on it's usage
> later down the line.
> 
> Sean

Sean, 
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
relearn what I did a few months ago often enough that I feel it's a necessity. 

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
useful. 

I've also used UML in the past for this, but find that It is often rather
obtuse in it's details. Now that DIA exists, I've played with it a little more
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
end?

It would be nice to be able to do some things visually, but more to the point,
I'd like some way of making it all more intelligible with a quick browsing. So,
if I know that the application is screwing up when doing XYZ, I need a quick
way to find what is going on where during XYZ, what variables/functions are
being called, and what files they might reside in. And of course, get this
level of broad/detailed information available without unduly slowing down or
distracting the programmer. Oh, and it has to be language independent as well.

Sigh.... 


-- 
Chuck Morrison
VA Linux - Western Region
Sr Systems Engineer




More information about the FRPythoneers mailing list