Zope 3 wiki → Developer Info → Proposals →
last edited 1 year ago by BaijuMuthukadan
created: 2004-02-26

SpringCleaningDay2004

Spring Cleaning Day 2004

Authors

StephanRichter, PhilippVonWeitershausen

Status

IsDraft

Problem

Some parts of the Zope3 source code are poorly documented and/or in bad cosmetic shape. Having well documented code that is easy to read and follows a common set of conventions is essential for the maintainability of a large project like Zope3.

Current identified defects

  • Many Headers and module doc strings do not conform to the Coding Style guide.
  • There are still files (especially C code) that do not have a valid ZPL 2.0 header. Done - Scott Pascoe
  • Also, some files have no docstring or a docstring that only includes the CVS id. A module's docstring should contain at least a title.
  • Many interface, method and attribute/field docstrings have insufficient docstrings. For example, the IPrincipal? docstring 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 contain things like "XXX to be done later" or empty strings.
  • Refactoring scars, e.g. in the zope.component package. The interfaces are inconsistent and services implement methods that are not in the interfaces (but should be).
  • There currently is a mixture of old-style and new-style classes which makes subclassing and the usage of features like super very unpredictable. Talking about super : it should be used instead of the old-style notation when calling a base class's method.
  • People seem to have different taste with how ZCML should be formatted, and seldomly look at the ZCMLStyleGuide. Inconsistent ZCML formatting is the result.
  • ZPTs? should contain valid XHTML. They should be validated against the XHTML DTDs? and reviewed for known browser issues (<br/> ==> <br />). For good style, each template should contain the XHTML 1.0 doctype declaration and the declaration of tal, metal and i18n namespaces.
  • The list of imports in many Zope3 modules is quite long. Sadly, most modules do not follow a certain order when importing these packages. Grouping together top-level imports, imports from zope and imports from zope.app is, among others, a good visual aid and helps identify package dependencies easily.
  • Thanks to Martijn Faassen and his importchecker tool, the number of unnecessary (unused) imports in modules is quite low. However, since we are using doctests, many modules import things at the module level that is needed by doctests. That does not only create false positives for the importchecker, it also creates sometimes unnecessary package dependencies. Therefore, imports needed by doctests should be imported in the doctests themselves.
  • Over many refactorings, we've added quite a number of backward compatibility setups. Most of them have been around longer than intended. It will not make much sense to use them in a post X3.0 setup; it might actually confuse people.

Proposal

To make a better release of Zope X3.0 possible, the event of a Spring Cleaning Day, where -- similar to a bug day -- the above mentioned defects would be fixed, is proposed. It would happen after the release of Zope X3.0 beta1 in April.

It is also suggested to make this (at least) an annual thing, since future code refactorings and additions will sure wander through Zope3's source without wiping their feet. Proof can be found in Zope2.

Tasks

  • Find a date for the Spring Cleaning Day.
  • Discuss issues listed below and update the Coding Style pages accordingly.
  • Assign tasks to participants.

Issues

  • Discuss the format of docstrings.
  • Discuss the copyright year issue. Though it has already been discussed in FileStructure, there's no conclusion. Should all file headers say Copyright 2001-2004? Or just the year of their creation or last modification? Or every year in which they were modified in a comma-separated list?

SR: Okay, I am making a decision on that now. We will adopt the Copyright 2001-2004 syntax, where the first year is the creation year and the last year the last time the file was modified.

  • Come to a conclusion regarding the ZCML style and update ZCMLStyleGuide.
  • When converting classes to new-style classes, subclass object, use __metaclass__ = type, or do both? Enforce consistency if one of the first two is chosen.
  • Discuss an import order. The suggestion is to:
    1. import modules from standard python library/global ackages
    2. import modules from the zope package
    3. import modules from the zope.app package

    while "import XYZ" goes before "from XYZ import ABC" and inside each group imports are sorted alphabetically. For example: 

           import os
       from smtplib import SMTP

       from zope.configuration import xmlconfig
       from zope.security import getProxy

       from zope.app.browser.form.widget import ListWidget
       from zope.app.tests import PlacefulSetup

Participants (and their tasks)

  • Stephan Richter -- ...
  • Philipp von Weitershausen -- ...
  • Mark McEahern? -- ...

    I'd be interested in making a utility to format ZCML.

  • Scott Pascoe -- ...

    I'm a newcomer to zope, but I can look and format.

  • Mohan Chandra...

    i can look on import order

(Please add yourself to the list if you're interested. If you're a newcomer, this is a good chance to get to know Zope3 better).



( 97 subscribers )