[Zope3-dev] defining interfaces

[Garrett Smith]

I want to make sure I have this right.

Under the auspices of "best practices", there are two approaches for
managing interface definitions. The one a developer chooses is based on
the need to manage a large number of interfaces.

Option 1 - Small, easily managed number of interfaces:

- Define all interfaces in a file "interfaces.py" located in the package
directory where the default implementations of the interfaces are
defined.

Example of Option 1:

  /mypackage
  -------------------
  interfaces.py
  foo.py

Option 2 - Large number of interfaces

- Define all interfaces in files that are located in an "interface"
subpackage. The interface files should have the same names as the files
containing the default interface implementations.

Example of Option 2:

  /mypackage
  --------------------
  interfaces/
  foo.py
  bar.py

  /mypackage/interfaces
  --------------------------------
  foo.py
  bar.py

Does this sound right? If, so, questions:

- If the only criterion for differentiating Options 1 and 2 is the
number/complexity of interfaces, what is a good rule of thumb for
developers to know when it's time to go from Option 1 to Option 2?

  - A specific number of interfaces? E.g. > 20, > 30?
  - The addition of subpackages? E.g. mysubpackage1, mysubpackage2,
etc.?

- From the Z3 codeline, it looks like a "project" should only have one
"interfaces" package (assuming Option 2) and that it should be defined
at the highest level of the project. E.g.

  Preferred Hierarchy
  -------------------------------
  /mypackage/
  /mypackage/foo/
  /mypackage/bar/
  /mypackage/interfaces/
  /mypackage/interfaces/foo/
  /mypackage/interfaces/bar/

  Discouraged Hierarchy
  -------------------------------
  /mypackage/
  /mypackage/foo/
  /mypackage/bar/
  /mypackage/interfaces/
  /mypackage/foo/interfaces/
  /mypackage/bar/interfaces/

If there's agreement on what the approach is, I'll write up something
for the docs.

Btw, if the above scheme is accurate, we should clearly define
"project", since that will expressly determine the level at which
interface definitions are organized.

Garrett Smith
Mojave Corporation


> -----Original Message-----
> From: Steve Alexander
> Sent: Saturday, April 05, 2003 4:06 PM
>=20
>> - In the event that "best practices" recommends that=20
>> projects should be  defined in some sort of package=20
>> structure, could we  eliminate option 1 above?
>=20
> I think so. Option 1 is really only for single-module projects.
>=20
>=20
>> This would leave the relatively simple decision of whether to
>> define interfaces in a module or a package, presumably=20
>> based on the size and complexity of the API.
>=20
> Right.
>=20