[Grok-dev] a Grok 1.0 release plan

[Martijn Faassen]

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