Q re documentation Python style

Ethan Furman ethan at stoneleaf.us
Tue Jun 10 05:25:56 CEST 2008

kj wrote:
> I'm a Perlhead trying to learn the Way of Python.  I like Python
> overall, but every once in a while I find myself trying to figure
> out why Python does some things the way it does.  At the moment
> I'm scratching my head over Python's docstrings.  As far as I
> understand this is the standard way to document Python code.  I
> think that's fine for simple functions, but I have some functions
> that require a very long docstring to document, and somehow I find
> it a bit disconcerting to stick a few screenfuls of text between
> the top line of a function definition and its body.  I guess I'm
> still a lot more comfortable with Perl's POD, which allows more
> flexibility on the placement of the documentation relative to the
> source code.
> Kynn

You might also look into using an editor that supports custom folding. 
Define docstrings as folds, then you only need open them when you want 
to read/edit them; the rest of the time, only one line is visible 
between the function header and the function.  I like Vim.  :)

More information about the Python-list mailing list