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/
On Monday 21 March 2005 18:10, Nicholas Jacobson wrote:
IIRC, Guido once mentioned that he regretted not setting function docstrings to come before the function declaration line, instead of after.
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? -- Anthony Baxter <anthony@interlink.com.au> It's never too late to have a happy childhood.
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
Brett C. wrote:
I am going to be -42 on this one. I personally love having the docstring below the definition line.... I can't really rationalize it beyond just aesthetics at the moment....
I completely agree that the current form is better. It reduces the temptation to use boilerplate docstrings. No comment is better than an uninformative comment. If you don't want to spend the time to write a comment, step back and let me read the code itself. If the docstring is below the declaration, you needn't repeat the declaration in the comment (and people are less tempted to do so). Documentation and code should come from a human mind, and should communicate to another human mind. Attempting to automate the task of documentation creates hard-to-read code, interrupted by large meaningless comments which, often as not, are copied from a template and incompletely editted to be appropriate to the given function. Sorry about the rant, but this is another of my hot buttons. The single most disappointing thing I encountered on one project in a large corporation was an operating system requirements document that was being developped. The group had, at one point, a twenty-two page document with no real content. Really, the twenty two pages included an introduction, conclusion, table of contents, appendix, and index. It just didn't have anything but section headings. It was a thrilling triumph of form over function; a real Suahuab aesthetic, to coin a term. --Scott David Daniels Scott.Daniels@Acm.Org
participants (4)
-
Anthony Baxter -
Brett C. -
Nicholas Jacobson -
Scott David Daniels