[Twisted-Python] Re: [Twisted-commits] Document the likley consequence of non running of unit tests

Glyph Lefkowitz glyph at twistedmatrix.com
Mon Sep 23 21:00:57 EDT 2002

On Mon, 23 Sep 2002 13:45:39 -0400, Itamar Shtull-Trauring <twisted at itamarst.org> wrote:
> Bruce Mitchener wrote:

> > Because I have patches in my tree that aren't checked in yet that add 
> > that documentation, along with docs for other parts of Woven, but 
> > Donovan and I have been discussing various changes to the widgets and 
> > how things work in that area.

This can be a valid excuse for code which doesn't have documentation.  In fact,
I prefer that upon its initial checkin, code be undocumented until a few of the
dev. team members can poke at it, see if it makes sense, and criticize any
serious flaws it has.

Twisted needs a lot more documentation, but in a platform where some parts are
stable and robust and others are growing and changing, lack of documentation of
some portions will keep people from using experimental code that really
shouldn't be supported in future versions.  (We can yell and scream all we like
about instability of some APIs, but if there is a complete, documented, but
buggy and poorly designed bit of code in the system, people will use it and
clamor when it is removed or the interface is fixed.)

> I rather tend towards your other opinion, that everything should have docs,
> even if it will change. But this does show the problem with requiring docs
> for everything leading to reverting code - everyone always has a reason why
> they didn't need to in *this* case. Or they didn't have time or whatever.

This is not entirely undesirable.  There are many, many bits of Twisted which I
am glad did not have documentation and died unceremonious deaths before they
had widespread exposure.  (Does anyone remember GLOOP?  No?  Good!)  I wish
twisted.web.widgets had stayed undocumented until Donovan had come along ;-).

Finally, even if a feature is complete and correct and will expect no changes,
keeping it out of the tree on the basis that there is no documentation is
counterproductive.  Such a feature could be documented after the fact, and
others using and learning it will often lead to better documentation than the
original author's specification would.  Code that breaks unit tests is in a
wholly different category.  Code that breaks unit tests means that the
functionality that someone else was already using is likely broken now.

In other words, code without docs moves us forward less than it might have.
Code without examples tests moves us backwards.

> Merciless taunting should be sufficient in most cases in solving this. 
> Although I'm tending towards outright violence against whoever is 
> responsible for twisted.python.reflect.refrump.

Man, you guys have _no_ sense of humor :-P.  Yes, that was just a leftover
function from an earlier attempt at rebuild(), intended for interactive use.
It was my fault, and it's gone now.

 |    <`'>    |  Glyph Lefkowitz: Traveling Sorcerer   |
 |   < _/ >   |  Lead Developer,  the Twisted project  |
 |  < ___/ >  |      http://www.twistedmatrix.com      |
-------------- next part --------------
A non-text attachment was scrubbed...
Name: not available
Type: application/pgp-signature
Size: 189 bytes
Desc: not available
Url : http://twistedmatrix.com/pipermail/twisted-python/attachments/20020923/6863cdbb/attachment.pgp 

More information about the Twisted-Python mailing list