[Python-Dev] PEP 287: reStructuredText Standard DocstringFormat

[David Goodger]

David Abrahams wrote:
>>> Is it just me, or are docstrings less-convenient than comments?
>> 
>> How do you mean?
> 
> I don't know, it's hard to put into words, but I'll try:
> 
> 1. 5 more characters just to get started. Probably a shift key too, if
> I'm going to be stylistically conformant with other work I've seen.
> ("""...""").

If the docstring is more than a few lines long, the quotes become average
out to less than "#" in comments.  Easier to edit docstrings; no per-line
prefix.

> 2. The docstring separates the function signature from its body, which
> tends to obscure the code a bit. I prefer prefix documentation.

I suppose that's valid.  It comes down to what you're used to.

You could put triple-quoted multi-line strings before the "def", but they
wouldn't be accessible or particularly useful.  Triple-quotes can be used as
multi-line comments, at least for temporary ones.

> 3. Weird indentation when the docstring spans multiple lines
> 
>     def foo(bar, baz):
>         """Start of doc
> rest of doc
> and some more doc"""
>         function_body()

The convention is to indent all lines of the docstring equally, and to put
the closing triple-quotes on a line by themselves.  I prefer to put the
opening triple-quotes on a line by themselves too.  It would end up looking
like this::

    def foo(bar, baz):
        """
        Start of doc
        rest of doc
        and some more doc
        """
        function_body()

> Documentation is really hard to start with, and every additional barrier
> to entry is unacceptable to me. Every time I write a doc string, I think
> of all 3 of the above things, which causes a little "cognitive
> dissonance", and makes it less likely that I'll write another.

You can still write prefix comments.  HappyDoc extracts them, but they're
not accessible from the running program or from the interactive interpreter.

Better in the long run (for you and others who use your code) to embrace the
features Python gives you.  Confusing otherwise.  Nobody's forcing you
though.

-- 
David Goodger    goodger@users.sourceforge.net    Open-source projects:
 - Python Docstring Processing System: http://docstring.sourceforge.net
 - reStructuredText: http://structuredtext.sourceforge.net
 - The Go Tools Project: http://gotools.sourceforge.net