launchpad-dev team mailing list archive

[Gary Poster <gary.poster@xxxxxxxxxxxxx>]

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.

Gary