Chris McDonough writes:
I'd like input on a proposal to standardize a little more on product distribution and packaging at http://dev.zope.org/Wikis/DevSite/Proposals/FinishedProductGuidelines. The idea is to come up with a set of packaging and documentation guidelines intended to be followed by product developers in order to provide a better user experience to people attempting to locate products and use products they get from Zope.org.
: All product documentation (besides API documentation) should be : written in Structured Text format. See : http://www.zope.org/Members/millejoh/structuredText for an explanation : of this format. I do not like structuredText very much unless for very simple texts. Especially, inline Python code is a pain. You will recognize this, when you look at Zope's own structured text documentation (--> API, default string argument values). I would suggest, to allow for structuredText or HTML. : Interfaces When I write code, the Interfaces can be directly extracted from the implementation (a long standing fight between me and DC). : Optional: General Coding Style : : When possible and reasonable, each class declared in the product : should live in its own module file. Module files with many (> ~ 5) : classes should be refactored into separate modules. Hugh, Python is not Java. Why should classes be separated into different files? You speak about meta-data standardization but in fact, the proposal suggest few standards. What about using something like Lars M. Garshol's "xsa" XML DTD? You will get more acceptance, when you not only state principles and guidelines but also explain their reason. For example: "Why it is desirable to separate logic from Zope wrapping"? Probably because it facilitates testing, increases application domain, makes for a clearer structure. Dieter