[Product-Developers] Re: Where does it hurt?

David Glick davidglick at onenw.org
Mon May 19 01:35:50 UTC 2008

On May 18, 2008, at 5:56 PM, Dylan Jay wrote:

> Martin Aspeli wrote:
>> Hi guys,
>> Following a long discussion with Dylan Jay (buried in another  
>> thread on Devilstick terminology), I thought I'd conduct an  
>> informal poll.
>> ==> As a customiser of Plone, or as someone wanting to build  
>> bespoke components that extend Plone, what do you find most  
>> confusing?
>> I think this could fall into a few categories:
>> - Areas where there's insufficient/poor documentation, but once you  
>> learn how to do something, it's clear how to proceed.
>> - Areas where there appears to be more than one approach, and it's  
>> not clear which one to choose
>> - Areas where Plone doesn't appear to have a good way to do something
> I think it hurts the most when something goes wrong. I write  
> something that I think should work, it doesn't, suddenly I'm faced  
> with understand everything I'm relying on.
> Debugging is a nightmare. Perhaps I'm not using the right tools. but  
> generally I try to read the code, which with the amount of  
> indirection these days is pretty hard to read. The fact thats its  
> not obvious where the definition the code I'm after is makes it  
> harder. For instance I was trying to find the schema definitions fot  
> ATCT the other day... and thats just z2. Trying to work out how to  
> the standard templates got connected in in plone.z3cform was even  
> harder.
> I'm not 100% sure how to fix this. A tutorial on how to read code?
> The slow startup time makes this worse of course because one way to  
> try and fix things is to try different stuff and see what happens.

FWIW, here are some cases from my experience that have seemed  
particularly hard to debug.  (Not trying to whinge here; just trying  
to catalog some possible areas for improvement)...
- Python scripts, since you can't see where you're at in pdb and it's  
hard to avoid stepping through z2 security stuff.  (Why do we still  
have these in the age of utilities and browser views, anyway?)
- Anything in a Quick Installer handler, since it seems to swallow  
- When working with utilities and adapters, figuring out why you're  
failing to look up something that you *thought* you had registered  
properly.  (but I can't think of a good generalizable way to make this  
- Any code that has an outrageous inheritance tree (e.g. Archetypes/ 
ATContentTypes stuff in particular).  I think this is the least of our  
worries though, since after a few months I had a decent sense of where  
I might look for things, and z3 techniques will make this less of an  
- This last one is more about documentation than debugging, but it's  
related.  For my first couple months of working with Plone, I tried to  
rely on api.plone.org way too much.  Then I realized that I was much  
more productive working with the actual source code and pdb.  This is  
probably not terribly surprising, nor an unreasonable expectation for  
a serious product developer.  But for someone who's just getting  
started, would it be too much to ask to have some auto-generated API  
docs that don't leave out pieces of the puzzle?  (For starters, you  
could augment the existing api.plone.org by having class docs include  
docstrings from the z3 interfaces the class is known to be  
implementing, link in doctests for a module, etc.)

I'm sure there are other places for improvement too :)  just my two  

David Glick
Project Associate

New tools and strategies for engaging people in protecting the  

davidglick at onenw.org
(206) 286-1235 x32

Subscribe to ONEList, our email newsletter!
Practical advice for effective online engagement

More information about the Product-Developers mailing list