On Sun, Jun 8, 2008 at 2:17 PM, kj <socyl@987jk.com.invalid> wrote:<br><div class="gmail_quote"><blockquote class="gmail_quote" style="border-left: 1px solid rgb(204, 204, 204); margin: 0pt 0pt 0pt 0.8ex; padding-left: 1ex;">
<br>
<br>
I'm a Perlhead trying to learn the Way of Python.  I like Python<br>
overall, but every once in a while I find myself trying to figure<br>
out why Python does some things the way it does.  At the moment<br>
I'm scratching my head over Python's docstrings.  As far as I<br>
understand this is the standard way to document Python code.  I<br>
think that's fine for simple functions, but I have some functions<br>
that require a very long docstring to document, and somehow I find<br>
it a bit disconcerting to stick a few screenfuls of text between<br>
the top line of a function definition and its body.  I guess I'm<br>
still a lot more comfortable with Perl's POD, which allows more<br>
flexibility on the placement of the documentation relative to the<br>
source code.<br>
<br>
I expect that the reply to this quibble about very long docstrings<br>
will be something like: if your function requires several screenfuls<br>
of text to document, then it is too complex or it is doing too<br>
much; refactor it into a collection of simpler functions that will<br>
have shorter docstrings.<br>
<br>
Fair enough.  In general I agree with this sentiment, except that<br>
I think that sometimes even simple functions require a lot of<br>
documentation.  For example, I want to document a function that<br>
takes a dictionary as argument, and this dictionary is expected to<br>
have 5 keys.  (When the number of mandatory arguments gets above<br>
4, I find that it's too difficult to remember their order, so I<br>
resort to using a dictionary as the single argument.)  The semantics<br>
for each of these keys needs to be described.  Plus, of course, I<br>
need to describe what the function returns.  That's a few screenfuls<br>
right there...<br>
<br>
I guess this is a rambling way to ask: are docstrings *it* as far<br>
Python documentation goes?  Or is there a second, more flexible<br>
system?<br>
<br>
Then again, I suppose that Python's relative formal rigidity is<br>
considered by many to be a strength.  Which means that, to be<br>
comfortable with Python, one has to learn to like this (relatively)<br>
rigid structure...<br>
<br>
But I thought I'd ask.  :)<br>
<br>
Kynn<br>
<br>
--<br>
NOTE: In my address everything before the first period is backwards;<br>
and the last period, and everything after it, should be discarded.<br>
<font color="#888888">--<br>
<a href="http://mail.python.org/mailman/listinfo/python-list" target="_blank">http://mail.python.org/mailman/listinfo/python-list</a><br>
</font></blockquote></div><br>If you use named parameters in your functions and methods, order is not so important...<br><br><font face="courier new,monospace">>>> def foo(a=None, b=None, c=None):<br>...    print a,b,c<br>

... <br>>>> b(c=1, a=2, b=3)<br>2 3 1<br></font><font color="#888888"><br clear="all"></font><br>-- <br>Stand Fast,<br> tjg.