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
