RetroSearch Browse

Mon Mar 21 15:23:45 CET 2005 · https://mail.python.org/pipermail/python-dev/2005-March/052334.html

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

Home - News ( United States | United Kingdom | Italy | Germany ) - Football scores

Showing content from https://mail.python.org/pipermail/python-dev/2005-March/052334.html below:

[Python-Dev] docstring before function declaration