kj a écrit :
(snip)
I think that sometimes even simple functions require a lot of
documentation. For example, I want to document a function that
takes a dictionary as argument, and this dictionary is expected to
have 5 keys. (When the number of mandatory arguments gets above
4, I find that it's too difficult to remember their order, so I
resort to using a dictionary as the single argument.)
Python supports keyword (named) arguments, so you don't have to remembed
the order, ie:
def func(arg1, arg2, arg3, arg4):
# code here
func(arg2=42, arg4="toto", arg3="truc", arg1="foo")
Also, with good enough naming (perhaps one of the most difficult part of
programming FWIW), you don't necessarily need an exhaustive
documentation of each and every detail.
(snip)
Then again, I suppose that Python's relative formal rigidity is
considered by many to be a strength. Which means that, to be
comfortable with Python, one has to learn to like this (relatively)
rigid structure...
Or to learn how to hook into the system. If you want to put the doc
before or after the function's body, it is not a big problem:
# doc after the function's body:
def func(args):
# code here
func.__doc__ = """
doc here
...
"""
# doc before the function's body:
def document(doc):
def _document(func):
func.__doc__ = doc
return func
return _document
@document(""" doc here
and here and here
etc...
""")
def func():
# code here
I wouldn't personnaly use any of the above styles, but as far as I'm
concerned, I don't write exhaustive docstrings. Good naming (somehow one
of the hardest part in programming IMHO) and simplicity (small simple
functions doing one thing each) already provide some part of the
documentation IMHO, and code always provides the most exhaustive
documentation you'll ever find !-)
--
http://mail.python.org/mailman/listinfo/python-list
