[Python-Dev] PEP 287: reStructuredText Standard DocstringFormat

[David Abrahams]

----- Original Message -----
From: "David Goodger" <goodger@users.sourceforge.net>


> 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.
("""...""").

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

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()


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.

-Dave