[Zope3-dev] defining interfaces

[Steve Alexander]

Garrett,

I'm really pleased that you're taking an interest in this. This is a 
subject that would benefit from some clear explanations.

> It sounds like creating an "interfaces" subpackage that contains a
> module for each interface is the most scalable way to manage interface
> definitions. Why not just make this the recommended approach, given the
> reasons you state?

I think all the ways I mentioned need to be "acceptable".
I would always recommend separating interfaces from implementation.


> I think it would be ideal to have a single recommended approach, even
> for small projects. This would simplify people's development decisions
> and help make projects more readable.

Well, when I look for the interfaces for a project, I find the project's 
root, and look for something called "interfaces". I expect to find 
either a directory or a module.

One thing we discovered about Zope 3 at the Rotterdam Sprintathon was 
that flatter directory structures are easier to understand and easier to 
maintain. This lead to the grand renaming and reorganisation of the Zope 
3 code into the form you see now.

I'm very much in favour of using the right arrangement for a particular 
project, rather than trying to make all projects fit just one 
arrangement. The right arrangement in this case is to balance these things:

* Keep the interfaces separate from the implementation

* Keep the filesystem representation as flat as is reasonable

* Divide things up if they'd otherwise be too big

See also http://www.python.org/doc/Humor.html#zen


> Perhaps there could be an exception for single file modules,
> but as these grow, developers will have to restructure anyway, yes?

Do these things always grow?

    "La perfection est atteinte non quand il ne reste rien à
     ajouter, mais quand il ne reste rien à enlever."
                                     Antoine de Saint-Exupéry

Perfection is attained not when there is nothing left to add but when 
nothing is left to remove.


> Btw, I'm not entirely clear on the term "project".

Many people have said that. I wish we had a good working definition of 
"project".

> For the sake of external development (i.e. not core), isn't all
 > development expressed in terms of registerable products?

No.


> Or do  you expect developers to ship frameworks that are not
> installed as  products?

Yes.
Although, I wouldn't use the term "frameworks" here. I expect developers 
to make available projects that are not themselves installed as products.


> In any event, I started on a "best practices" doc for this topic,

Great!

> but found the distinctions between the three alternatives to be a
> bit subtle and not obviously useful. I'm curious as to what people
> think here.

There really are only two alternatives. The other differences are just 
to do with the choices you always have about how to organise python code 
on the filesystem.

The two alternatives I'd recommend are:

1:
     project.py
     iproject.py

2:
     project/
     project/interfaces.py

   or, if you have lots of interfaces

     project/
     project/interfaces/

--
Steve Alexander