[Zope3-dev] Code cleanup day

[Stephan Richter]

Hello everyone,

while writing the book for Zope 3, I saw a lot of code. I noticed that certain 
sections of the code are in really bad shape in terms of cosmetics. The 
common issues are:

1. Headers and module doc strings do not conform to the style guide. There are 
still files (especially C code) that do not have a valid ZPL 2.0 header. 
Also, some files have no doc string or a doc string that only includes the 
CVS id. We should at least have a title in the module doc string.

2. Interface, Method and Attribute/Field doc strings. I noticed that many 
interfaces have insufficient doc strings. For example, if I remember right, 
the IPrincipal doc string talks about how a principal is used in a particular 
context, but does not explain what the principal is in the first place. In 
even worse cases attribute explanations contained things like "XXX to be done 
later" or empty strings. If the API doc tool is supposed to be helpful, we 
need to have good doc strings. There are some minor things about the format 
of doc strings, but we can discuss this later.

3. Refactoring scars. While our merciless refactorings went pretty good and we 
often cleanup after ourselves, scars from the many refactorings start to 
show. A good example is the zope.component package. The interfaces are 
inconsistent and services implement methods that are not in the interfaces 
(but should be). This is noone's fault, just a result of time. But I think we 
should remove these dirty spots, since it will make it easier for the 
incoming newbie to see what's going on.

I am sure there are a couple of things I missed, but this should cover the 
majority. 

To make a better release of Zope X3.0 possible, I would suggest that we have a 
code cleanup day after Zope X3.0 beta 1 somewhen in April. 

What do you guys think? Would you participate? Note that there is something to 
do for anyone, from the total beginner to the core hacker.

Regards,
Stephan
-- 
Stephan Richter
CBU Physics & Chemistry (B.S.) / Tufts Physics (Ph.D. student)
Web2k - Web Software Design, Development and Training