[Zope3-dev] Re: New Pyskel changes

[Steve Alexander]

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.

--
Steve Alexander