launchpad-dev team mailing list archive

[Curtis Hovey <curtis.hovey@xxxxxxxxxxxxx>]

On Mon, 2010-03-01 at 11:28 -0500, Gary Poster wrote:
> On Mar 1, 2010, at 10:57 AM, Julian Edwards wrote:
> 
> > On Monday 01 March 2010 15:40:25 Aaron Bentley wrote:
> >> Julian Edwards wrote:
> >>> Precedent.  Pretty much most of our model objects already have this.  Our
> >>> doc strings are mostly awful and where they are not awful they are
> >>> mediocre.
> >> 
> >> Our classes which implement interfaces have deliberately content-free
> >> docstrings, and I really wish they didn't.  Having the documentation of
> >> lp.code.model.Branch just saying "See `IBranch`." over and over is not
> >> useful.
> >> 
> >> It is very useful to have the documentation and the implementation in
> >> the same place, so that the documentation can serve as a guide to
> >> understanding the implementation.  It also makes it easier to spot and
> >> fix errors in the documentation.
> >> 
> >> Aaron
> >> 
> > 
> > Huge +1.
> > 
> > I've always hated that we document the interface and not the model.  Does 
> > anyone remember why we do it that way?
> 
> Zope pattern.
> 
> The pattern makes more sense IMO when you are designing shared
> systems, libraries, or framework.  Less sense when you are writing
> application code.  The Grok pattern is to forego interfaces in favor
> of classes in application code--code that is hooking things or
> plugging things together, rather than providing plug-points.
> 
> I'd be in favor of that.

I think the underlying problem here is that most interfaces in Launchpad
has only one implementer. Deriving the interface from the model seamed
ideal at one point (I believe there is a bug in foundations regarding
this). I think the point is largely moot now because we are composing
our interfaces and models from multiple interfaces to accommodate API
permissions.


-- 
__Curtis C. Hovey_________
http://launchpad.net/

Attachment: signature.asc
Description: This is a digitally signed message part