Martin P. Hellwig wrote:
Hi all,
I've been toying with python for about two years now. Not every day,
just when I encounter something in my job (sysadmin) repetitively dull.
The amazing thing is that like any other language (natural or not)
learning it more gives you power to express your thoughts better and
create something from nothing, for me this is something I can only
compare to freedom.
However since I'm learning more of python I've struggled with
commenting, how should I've comment my code? I'm not talking about the
style but more on the concept itself, things that where a couple of
month ago a bunch of monkey poop is now as easy as reading a comic.
I always give a brief description on what the code is supposed to do and
I suppose that any serious coder knows way more then me about
programming so I don't bother to comment that much since it mostly (in
my eyes) just clutters up the code and makes it actually harder to read.
Though this makes me uncomfortably, commenting so little, I was thinking
that perhaps something like doctest (I'm not so much into unit testing
or the equivalents at this moment) has the side affect to make my code
more understandable and readable. Any practical experience you'd like to
share with me, any other comments are welcome too of course :-)
I have found it useful to familiarize myself some tool such as epydoc
and write comments in the function doc-string. For example,
def doit(stuff, beta, cycles):
"""
Does nothing with I{stuff} in an infinite loop by applying a null
operation. The I{cycles} parameter is multiplied by infinity.
@param beta: null operator not to be applied to stuff
@type beta: callable
@type cycles: int
"""
This explains paramaters, etc., for you and other users of your API and
paves the way for automatically generated documentation. Note that it
would be excessive to comment each and every parameter, etc. Once the
code is working correctly, a lot of in-line comments can be removed.
Usually, in python, correctly working code is self explanatory at the
implementation level, especially if you attempt to code "pythonical ly"
(which can roughly be defined as the best practices according to the
python community or the community subset who post to comp.lang.pytho n).
If you find that your code gets very complicated and needs excessive
commenting to understand, try to factor it into hierarchically related
simpler functions and classes and comment each individually using
doc-strings. In essence, think about commenting the interface rather
than the implementation.
Use module level doc-strings (comments) to gather usage and explanation
notes for the most useful functions. This allows users (for example,
you) to use your libraries without burrowing into the automatically
generated documentation for each and every function.
Other tools may be as useful as epydoc, but this is the general strategy
I have converged upon.
James
