[Zope3-dev] defining interfaces

[Garrett Smith]

Looking through the Z3 codelines, it's hard to see a consistent pattern
wrt interface organization. I'm assuming that no one wants another
massive file reorganization, so I'm thinking in terms of what non-core
Zope 3 developers should follow.

Preliminary Definition of Project:

> a body of code that is within some package that may be=20
> independently maintained, and that well-defined dependencies on other=20
> code and other projects

Procedure for Small Projects (no subpackages, no subprojects):

- Define all interfaces in a file "interfaces.py"

Procedure for Large Projects (at least one subpackage or subproject):

- Define all interfaces in a subpackage named "interfaces"

- Maintain a "mirror" between the top-most package directory and the
interface subpackage directory. I.e. when a subpackage is added to the
project, add a subpackage to "interfaces" of the same name.

- Default interface implementations should be defined in files/modules
of the same name as their respective interfaces.

I realize the second procedure deviates a bit from your last message,
but here's where I'm coming from:

- Trying to keep things drop-dead-simple, without oversimplifying. In my
experience, users just want to know how to do something...the fewer
things to ponder/weigh, the better.

- I'm not thinking in terms of how things are now, but in terms of how
new developers should be advised.

- The simplest delineation between project types is "small" and "large".
Large is characterized as having subpackages/subprojects. Sure, there
might be exceptions, so this is presented as a guideline. Ultimately,
the developer can figure out what's small and what's large.

- Once the decision has been made to go with a "large" project
structure, the developer should maintain a mirror within the
"interfaces" package, as much as is possible. My thinking here is that
this approach:

  - simplifies the thinking for the developer -- file for file,
directory for directory, things stay mirrored.

  - simplifies things for the reader/user of the project -- file for
file, directory for directory, the reader/user knows what expect.

I've spent some time in the Java world where this is big issue. It's
important that the user of a "project" be able to track down default
implementations for interfaces and vise versa. In Java, these class
types are almost always in the same package and follow a naming
convention:

   mypackage
   -----------------------
   Foo - interface
   DefaultFoo - default implementation

Very simple indeed. My recommendation above is based the (naive?)
assumption that a similarly clear approach is possible/good for Zope 3.

Garrett Smith
Mojave Corporation