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 Python-Dev@python.org 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
On Tuesday 22 March 2005 05:58, Nicholas Jacobson wrote: Oops, you're right. What I should have said is to use a blank docstring as follows: It's still unclear to me what a file containing a single docstring followed by a def() line means. And this ambiguity doesn't seem to be solvable, so I'm a solid -1 on this change. (In addition, I should note that I tried editing a moderate sized file to put the docstrings before the defs - to my eyes, it made the file more cluttered and much less pleasing to the eye) -- Anthony Baxter [EMAIL PROTECTED] It's never too late to have a happy childhood. ___ Python-Dev mailing list Python-Dev@python.org 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 Python-Dev@python.org 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
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. ___ Python-Dev mailing list Python-Dev@python.org 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
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 ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
Fwd: [Python-Dev] docstring before function declaration
Nicholas Jacobson wrote: IIRC, Guido once mentioned that he regretted not setting function docstrings to come before the function declaration line, instead of after. [ examples deleted ] 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? Please don't. All class attributes are declared within the class. Pulling out the docstring would make it an exception. The current situation is very clear and easy to explain to newbies. If you feel the current position of the docstring may be the first attribute's docstring, insert a newline at the proper positions to separate the two. It works for me. --eric ___ Python-Dev mailing list Python-Dev@python.org 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
Nicholas Jacobson wrote: 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. -1 on all this making of blank lines significant. Currently I can leave some space before/after a docstring without breaking anything. This can help readability, especially for class docstrings. -- Greg Ewing, Computer Science Dept, +--+ University of Canterbury, | A citizen of NewZealandCorp, a | Christchurch, New Zealand | wholly-owned subsidiary of USA Inc. | [EMAIL PROTECTED] +--+ ___ Python-Dev mailing list Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
[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 Python-Dev@python.org http://mail.python.org/mailman/listinfo/python-dev Unsubscribe: http://mail.python.org/mailman/options/python-dev/archive%40mail-archive.com
