Documenting functions/methods/classes
Tuesday, February 12, 2008
There are several simple guidelines for writing functions or methods (guidelines that I like that is).
- Keep them clean, don't intersperse them with comments. If they require more then one or two inline comments it's too complicated and you should restructure.
- Keep them short, it should fit on one screen. I'm flexible, a screen is an emacs buffer, not a vi in a terminal as Linus requires.
- Write a clear description at the top, explaining parameters, return values, exceptions etc whenever these things might not be blatingly obvious in a month's time. As soon as you explain one parameter you you should describe the whole lot though.
In C this is quite nice, it looks like this:
/** Print an integer number
*
* The number is printed to stdout. Really that's
* all there is to it.
*
* param - The integer to print.
*/
void my_func(int param)
{
printf("This is an integer: %d", param);
}
While in Python this would look like this:
def my_func(param)
"""Print a number
The number is printed to stdout. Really that's
all there is to it.
param - The number to print.
"""
print "This is a number: %d" % param
While python code is generally very lovely readable this is something that annoys me about it. Suddenly my function definition is separated from the code by the docstring, often causing the definition and the code not to fit on one screen anymore (it is foolish IMHO to require the documentation and code to fit on one screen, given my documentation conventions).
While I understand every reason for the way things are and acknowledge that it probably won't ever change it still annoys me from time to time so I felt like moaning about it.
4 comments:
Anonymous said...
I've always found large bodies of text in code distracting. Especially in
Python it just looks so nice and clean to have very sparsely documented
code. Of course, sparse documentation can be highly annoying for the
maintiner of said code.
Python's zope.interface package let's you separate documentation from
implementation. This has the disadvantage that you need to look elsewhere
in the code for the documentation, but the advantage is that you can give a
tricky subject a proper treatise without needing to scroll to see
method signature and body.
zope.interface works when used in conjunciton with zope.component
so that you can do the whole "pluggable implementations" thing, but in cases
where you are not using the component aspect you can do an import with
"implements as documented" to make it cleared that you are using interfaces
only for documentation.
Also note that interfaces are documented from the perspective of the
caller, so you don't document "self" in a method signature since that's
not supplied when you pass a message to that object. This means that you
can more easily cut-n-paste from an interfaces method signatures than an
implementations method signatures :)
>>> from zope.interface import implements as documented
>>> from zope.interface import Interface
>>>
>>> class IEggbeater(Interface):
... "Beats on eggs"
...
... eggyness = Attribute("How much egg needs to get beat")
...
... def whip_it(power_level):
... "Whip up the eggs at a desired power level"
...
>>> class Eggbeater(object):
... documented(IEggbeater)
...
... eggyness = 500
...
... def whip_it(self, power_level):
... return self.eggery * power_level
...
Mikko Ohtamaa said...
I recommend you to check Epydoc:
http://epydoc.sourceforge.net/
And if you feel you have something to contribute, check this ongoing thread
http://sourceforge.net/mailarchive/forum.php?thread_name=7b5b293c0802141901s12378271jcc068ba8d7d86902%40mail.gmail.com&forum_name=epydoc-devel
My personal view is that commenting should *not* be separated commenting, since it tends to drive developers lazy and leave commenting out. Zope/Plone is infamous for its steep learning curve.
Mikko Ohtamaa said...
Spellchecking :(
Commeting should *not* be separated fromcode.
wheat, if comments get on your face, get a decent editor which supports comment folding (hides comment until they are clicked/cursor moved in).
Bob Erb said...
There are standards for doc strings. See PEP 257 for details.
Post a Comment