Am 15.01.2006 um 20:33 schrieb Christian Boos:
Ah, another convention that comes to mind: the embedded documentation.
There are basically 2 styles:
def abc():
"""One liner, says what abc is about
Now, more detailled documentation about abc, it's arguments,
return values, etc.
"""
And:
def abc():
"""
This is abc's doc. Please read on...
"""
There were several back and forth changes between these 2 styles.
I think the first one should be preferred, although there are still
areas
where the second one is prevalent (e.g. trac/versioncontrol/api).
Definitely the first (yeah, I got that wrong in the past). This
confirms to the Python coding conventions, and the first line often
treated specially, serving as the summary (similar to everything up
to the first dot in javadoc).
One exception to the rule: test cases... if you use the "summary"
line for documenting test methods, the unittest module will use that
summary as the name of the test, which I personally find rather
inconvenient (harder to identify the test in question).
Cheers,
Chris
--
Christopher Lenz
cmlenz at gmx.de
http://www.cmlenz.net/
_______________________________________________
Trac-dev mailing list
[email protected]
http://lists.edgewall.com/mailman/listinfo/trac-dev
