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/
signature.asc
Description: This is a digitally signed message part
_______________________________________________ Mailing list: https://launchpad.net/~launchpad-dev Post to : [email protected] Unsubscribe : https://launchpad.net/~launchpad-dev More help : https://help.launchpad.net/ListHelp
