[Python-Dev] PEP 287: reStructuredText Standard DocstringFormat (original) (raw)

Guido van Rossum guido@python.org
Sat, 06 Apr 2002 13:47:26 -0500

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

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