[Python-Dev] PEP 287: reStructuredText Standard DocstringFormat

[Guido van Rossum]

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

Depends on how long your comment is going to be.  For long comments, a
on each line gets boring quickly, and not all editors know how to
reformat such comment blocks right.

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

You have a small point there.

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

Don't do this!  There's an explicit rule that doc strings should be
indented like the code containing them, and all docstring processors
are supposed to compensate for this.  Please write this, like
everybody else does:

    def foo(bar, baz):
        """Start of doc

	rest of doc
	and some more doc"""
        function_body()

Also note the blank line after the first line -- the first line is
supposed to be a one-line summary of the function (for use in
abbreviated help balloons, overviews, and so on).

> 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.

Time for you to start reading more Python code -- I've never heard
this excuse before.

--Guido van Rossum (home page: http://www.python.org/~guido/)