> 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/)
RetroSearch is an open source project built by @garambo | Open a GitHub Issue
Search and Browse the WWW like it's 1997 | Search results from DuckDuckGo
HTML:
3.2
| Encoding:
UTF-8
| Version:
0.7.4