Comments on me->flub: Documenting functions/methods/classes

There are standards for doc strings. See PEP 257 f...

2008-02-17T23:03:00.000Z

There are standards for doc strings. See PEP 257 for details.

Spellchecking :(Commeting should not be separate...

2008-02-15T20:14:00.000Z

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).

I recommend you to check Epydoc:http://epydoc.sour...

2008-02-15T20:12:00.000Z

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.

I've always found large bodies of text in code dis...

2008-02-13T06:52:00.000Z

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
...

Comments on me->flub: Documenting functions/methods/classes

There are standards for doc strings. See PEP 257 f...

Spellchecking :(Commeting should *not* be separate...

I recommend you to check Epydoc:http://epydoc.sour...

I've always found large bodies of text in code dis...

Spellchecking :(Commeting should not be separate...