[Python-Dev] docstring before function declaration (original) (raw)

Brett C. bac at ocf.berkeley.edu
Mon Mar 21 15:23:45 CET 2005

Nicholas Jacobson wrote:

IIRC, Guido once mentioned that he regretted not setting function docstrings to come before the function declaration line, instead of after.

He did, but I don't know how strong that regret is.

i.e.

"""This describes class Bar.""" class Bar: ... Or with a decorator: """This describes class Bar.""" @classmethod class Bar: ... Versus the current method: class Bar: """This describes class Bar.""" def foo: ...

I am going to be -42 on this one. I personally love having the docstring below the definition line. So much so, in fact, that in personal C code I use the same style for documentation. I find it easier to browse the source since where a definition starts is much cleaner (yes, syntax highlighting and searching for \s*def works as well, but I am thinking when you are just scrolling).

Beyond that I can't really rationalize it beyond just aesthetics at the moment. But I definitely prefer the current style.

-Brett

More information about the Python-Dev mailing list