[Python-Dev] docstring before function declaration
IIRC, Guido once mentioned that he regretted not setting function docstrings to come before the function declaration line, instead of after. 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: ... where the docstring looks like it refers to foo, not Bar. I think that commenting the function before its declaration, at the same tabbed point, increases the code's readability. What do you think about making this change at some point (e.g. Python 3000)? Or if not, then having the option to toggle to this layout? Thanks, --Nick Jacobson __ Do you Yahoo!? Yahoo! Small Business - Try our new resources site! http://smallbusiness.yahoo.com/resources/ ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] docstring before function declaration
Rule #1: If the docstring is the first line of a module, it's the module's docstring. Rule #2: If the docstring comes right before a class/function, it's that class/function's docstring. > How do you distinguish between a docstring at the > top of a module > that's immediately followed by a function? Is it > the module docstring > or the function docstring? It's both. The docstring would be assigned to both the module and the function. This is a *good* thing when there is a module with only one function in it. i.e. there should only be one docstring for both, and this saves repetition of that docstring. If a programmer wanted a docstring for the function but not the module, a blank first line would do the trick. A docstring for the module but not the function? Put a blank line between the module's docstring and the function. --Nick Jacobson __ Do you Yahoo!? Yahoo! Small Business - Try our new resources site! http://smallbusiness.yahoo.com/resources/ ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] docstring before function declaration
Oops, you're right. What I should have said is to use an empty docstring as follows: """""" """Function docstring.""" def foo: ... or: """Module docstring.""" """""" def foo: ... So the first docstring is the module docstring, and the next is the first class/function. And again, if there's only one, it will belong to both. --- Anthony Baxter <[EMAIL PROTECTED]> wrote: > On Monday 21 March 2005 20:08, Nicholas Jacobson > wrote: > > > How do you distinguish between a docstring at > the > > > top of a module > > > that's immediately followed by a function? Is > it > > > the module docstring > > > or the function docstring? > > > > It's both. The docstring would be assigned to > both > > the module and the function. This is a *good* > thing > > when there is a module with only one function in > it. > > i.e. there should only be one docstring for both, > and > > this saves repetition of that docstring. > > > > If a programmer wanted a docstring for the > function > > but not the module, a blank first line would do > the > > trick. A docstring for the module but not the > > function? Put a blank line between the module's > > docstring and the function. > > Yuk. This is magic taken to a ridiculous level. Note > that > "blank lines" currently have no meaning in Python, > and adding > a meaning to them is not my idea of a good thing. > > -- > Anthony Baxter <[EMAIL PROTECTED]> > It's never too late to have a happy childhood. > __ Do you Yahoo!? Yahoo! Small Business - Try our new resources site! http://smallbusiness.yahoo.com/resources/ ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Re: [Python-Dev] docstring before function declaration
Oops, you're right. What I should have said is to use a blank docstring as follows: """""" """Function docstring.""" def foo: ... or: """Module docstring.""" """""" def foo: ... --- Anthony Baxter <[EMAIL PROTECTED]> wrote: > On Monday 21 March 2005 20:08, Nicholas Jacobson > wrote: > > > How do you distinguish between a docstring at > the > > > top of a module > > > that's immediately followed by a function? Is > it > > > the module docstring > > > or the function docstring? > > > > It's both. The docstring would be assigned to > both > > the module and the function. This is a *good* > thing > > when there is a module with only one function in > it. > > i.e. there should only be one docstring for both, > and > > this saves repetition of that docstring. > > > > If a programmer wanted a docstring for the > function > > but not the module, a blank first line would do > the > > trick. A docstring for the module but not the > > function? Put a blank line between the module's > > docstring and the function. > > Yuk. This is magic taken to a ridiculous level. Note > that > "blank lines" currently have no meaning in Python, > and adding > a meaning to them is not my idea of a good thing. > > -- > Anthony Baxter <[EMAIL PROTECTED]> > It's never too late to have a happy childhood. > __ Do You Yahoo!? Tired of spam? Yahoo! Mail has the best spam protection around http://mail.yahoo.com ___ Python-Dev mailing list [email protected] http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
