[Python-Dev] PEP 287: reStructuredText Standard DocstringFormat
Guido van Rossum
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"""
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"""
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
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/)