[Python-Dev] docstring before function declaration

[Brett C.]

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