[Zope3-dev] Re: New Pyskel changes

[Tres Seaver]

On Tue, 2002-07-09 at 08:33, Steve Alexander wrote:
> Guido van Rossum wrote:
> > [Stephan]
> > 
> >>Often interfaces are very "clean" and simple. I think having
> >>__doc__-copying statements flying around everywhere makes is quiet a
> >>bit dirty looking. But then I am the extreme case of having
> >>good-looking readable code. :-)
> > 
> > 
> > I encourage a change to pyskel.py that copies the docstring from the
> > interface into the source, rather than copying it at run-time.  I
> > agree that the run-time copying does nobody any good and makes it
> > ugly.  The main use for docstrings is still for the benefit of the
> > human who reads the source code.  Having to look in a different file
> > for the doc string disrupts the process of understanding the code.
> 
> I think there are different requirements during development when the 
> interfaces may change and the hierarchy of interfaces may change, and at 
> deployment when the interfaces are more fixed.
> 
> Having the full docstring in the methods at deployment is good. Having 
> the full docstring in the methods during design is a problem, because 
> there are many places to keep things in synch.
> 
> I've generally found that I want to use pyskel near the start of 
> development.
> 
> 
> I'd be in favour of a tool that could re-apply docstrings to code, 
> carefully changing "See Foo.Bar.Baz" style minimal docstrings into full 
> copies of the originals. I could then use the cross-reference style 
> during development, and switch to the full style once I'm sure the 
> interfaces are fixed.

Agreed;  copying docstrings from interface to implementation opens up
the opportunity to modify them in one place and not the other.  I have
found that the "See IFoo" docstring is perfect when used in conjunction
with a tags-aware editor;  I can jump immediately to the interface using
the tag.

Tres.
-- 
===============================================================
Tres Seaver                                tseaver@zope.com
Zope Corporation      "Zope Dealers"       http://www.zope.com