[Zope3-dev] Big import blocks

[Guido van Rossum]

[me]
> > Jim's always on a crusade against "dead chickens" (arbitrary
> > things you have to do before you can do what you want to do).  I'm
> > beginning to count the blocks of "from zope..... import ...." at
> > the top of every Python module a huge dead checken.

[Jeffrey]
> Those big import blocks, and being able to follow them, is the only
> way one can even figure out Zope 3 right now.  "zapi" is a good
> idea, but it better be documented extremely well and that
> documentation better be extremely easy to get to.

Yes, good point.

> The only real documentation right now is the code, and the code
> isn't always easy to follow (nicely - the code is more explicit and
> predictable than Zope 2, but there's also a lot more going on).
> 
> So all of those 'zapi' things better have real docstrings, so I can
> at least try to learn them by using help(zapi.getService) in the
> interpreter without being told "see IGetServices".

Agreed, though this is a separate issue: things like traverse() or
getAdapter() currently have no docstrings at all.  This in part
because Zope 3 isn't finished yet, in part because Jim's philosophy
about documenting Zope 3 was to try and separate the documentation
from the code, by putting it in interfaces.  I think I've convinced
him that it's not wrong to put real documentation in implementation
docstrings too, now all we need is a sprint to add docstrings to all
the right places.

One problem I've found with sprints is that often there's a desire to
move on quickly -- the name suggests this and there's also the issue
that sprints are bounded in time -- which means that developers
sometimes don't write docstrings.  I think this is a mistake, and I
recommend that sprinters try to come up with reasonable docstrings as
they go.  It's okay if the docstrings aren't perfect or occasionally
contain typos and incomplete sentences; there's a host of people who
can fix those.  But if there are *no* docs, the intent of the code can
only be guessed from its implementation, which is usually
overspecified (and sometimes underspecified, i.e. incomplete!).

> The dead chicken right now is not the amount of imports, it's being
> able to grasp what you need to do, what you need to import, how
> things work (enough to feel confidant in doing your own work), and
> of course, ZCML (I still think most new users will spend more of
> their time getting comfortable with ZCML than with anything else, at
> least - based on my own experiences).  I'd rather someone tell me
> what the ObjectHub is, and when, where, and how to use it, than make
> it easier for me to import.

Sure.  Getting familiar with ZCML is a separate issue IMO.  Reference
docs for ZCML are quite easy to obtain (it's all in zope3/doc/zcml/,
most of which is auto-generated from <description> tags in the meta
ZCML), but it could use a good tutorial.  I guess the same is true for
other aspects of "grasping what you need to do".  I'm still grappling
with this a lot in many places.  I've recently helped Jim write a
tutorial for adding a service, which ended up containing a lot of
tutorial material for writing browser views.  This is currently on the
local-utility-branch branch; I expect that Jim will merge it into the
trunk soon.  The tutorial will be src/zope/app/services/README.txt.
Feedback is welcome.

--Guido van Rossum (home page: http://www.python.org/~guido/)