[Grok-dev] a Grok 1.0 release plan
Martijn Faassen
faassen at startifact.com
Sat Nov 29 07:43:57 EST 2008
Hey,
Brandon Craig Rhodes wrote:
> Martijn Faassen <faassen at startifact.com> writes:
>
>> I think we should consider calling the next release of Grok: Grok 1.0.
>
> I note that most of the Grok code that I have seen violates PEP-8 by
> being almost entirely devoid of docstrings (not to mention comments). I
> have been thinking about going through and adding some simple docstrings
> to make it easier for both newcomers to the code, and us old-timers with
> bad memories.
One of the problems with docstrings in Zope 3 code is that we tend to
place them in interfaces.py. Would you duplicate things? Very long ago
in Zope 3 we'd put in a marker that said "see .interfaces.IFoo.bar" for
every method, but that's rather ugly and hard to maintain.
An automatic introspector can automatically associate the docstring on a
method on an interface with the method itself of the class that
implements the interface. Whether this happens in practice is another
discussion. :)
> Is this something I should try doing before 1.0?
Sure - this is a low-risk enhancement. I'd limit your efforts to grok,
grokcore.*, grokui.* and martian - let's not delve into zope.* land. :)
> What is the Zope
> approach toward docstrings - are they frowned upon? From the almost
> entire lack of them in Zope code, I wondered if they were considered a
> bad idea, and if the code was supposed to "just be clear enough" that no
> docstrings were needed to define what things do.
We don't have the attitude that docstrings are a bad idea or that code
should be clear enough by itself: we have docstrings in interfaces. We
also have a lot of doctests that hopefully say something about the code
as well.
> But, if it were up to me, I'd like the code to have docstrings, and I'm
> willing to add them - but can put my efforts elsewhere if everyone else
> thinks that's a waste. ;-)
I propose you add docstrings to methods where the method isn't already
defined in an interface with a proper docstring there. Consider at each
point whether this is actually something that should be added to the
interface instead; we might've forgotten some methods or attributes in
places.
If the method on the interface already has a docstring, I propose you
just say: "see <IFoo>", where <IFoo> is an interface that this class
implements (either directly or through a subclass relationship). I think
a marker like this is better than nothing at all, as at least that gives
a hint to the reader what's going on, and the docstring adder won't then
accidentally add a docstring. :)
You can also add docstrings to most classes - sometimes the class will
implement a single interface that will contain the bulk of the
explanation, but that is the general explanation of the interface, and
doesn't explain why that particular class is there implementing it.
Regards,
Martijn
More information about the Grok-dev
mailing list