[Twisted-Python] Updated defer.html

[Clark C. Evans]

On Sun, Mar 09, 2003 at 01:12:22AM -0500, Steve Waterbury wrote:
| > You've sacrificed clarity for runnability.  
| Having read it carefully, I have to agree with Andrew here.  

Runnable vs clarity is a false choice.  If it isn't runnable then
it has no hope of being clear.  [clear changes to already runnable
code counts as runnable]

In fact, I had a complete mis-understanding of what Deferred
was all about for quite some time, mostly a fault of that
document for not having a runnable example.   The focus on 
'clarity' failed to show what Deferred actually *does*; it
had stuff, for example, about the main reactor event loop,
which is a completely othogonal issue, you don't neven need
the twisted reactor to use Deferred.   By the previous
documentation not focusing on a *tangable* runnable result
the explanation sunk into ickyness.

| Here I disagree.  Newbies are generally served better by 
| examples with lots of (germane) comments ... but not 
| extraneous stuff, like the Timer.  And I think it would be 
| "nice" if they were executable, but if it comes down to 
| choosing between clarity and executability, clarity should win.  

Documenting Deferreds suffers from a bootstrap problem; it is 
advantageous to introduce Deferreds before Threads, but to 
understand why you need Deferrerds you must already have
read about Threads.   The typical solution to a bootstrap 
documentation problems is to iterate into a circle, introduce
each concept and then after both concepts are glossed over
going into more detail about each one.   An introduction 
to threads, and the Timer is the simplest threaded operation,
is essential for motivating Deferreds...  And, to be a bit
defensive, you can't jump on my case here as examples later
on use the Timer.

Suggestion for improvement:

  Move the 'timer' example into the first part showing
  how a blocking operation becomes threaded, and showing
  how Python (without Twisted) supports callbacks.  

  Then, use this example of Python's callbacks to describe
  how it has several problems: (a) it doesn't handle errors
  well, (b) it doesn't allow for more than one callback, etc.

  Finally, re-write the timer example using Deferred for a 
  callback.   In this example, put the previously introduced
  code in a *grey* font so that it isn't destracting.

But, really, all examples should be completely runnable
or else you make a serious risk of losing the reader.

| > perhaps it's overly jargonistic, but it is the way I think about Deferreds;
| > they are the primary tool Twisted provides to abstract away blocking
| > operations into a fundamentally asynchronous framework.
| 
| Total agreement.  If they don't know what "asynchronous" 
| means, they can look it up!  Sheesh, it's a standard term.  
| (Twisted-specific jargon is not a problem in the docs 
| either, as it is always defined when introduced.)

Deferreds have *nothing* to do with deferring execution.  They are
only an improvement/embellishment on the Python callback mechanism.
That they are very useful in asynchronous contexts is nice, but
that isn't what they do - they don't provide asychronous execution.


| > Again, with the next two examples I think you've obscured the point in your
| > efforts to make everything explicit.  I'd rather have a 10 line example
| > that illustrates a concept, than a 20 line example that obscures the same
| > concept behind irrelevant method definitions, etc.  ...
| 
| Agreed also.  
| 
| That said, I think there are cases where the in-line examples seem
| a trifle too elliptical.  I'll have to be more specific, I know, 
| so I'll send an example when I have time.  

Well, I disagree with both of you here.  You need *all* of
the code so that a newbie doesn't have to fill-in the 
details, and get frustrated when they don't grok it.

In general, examples should build on the previous example,
and to make things clear, code that hasn't changed could
be made grey; or code that has changed can be made bold.
Use visual clues.  Electrons on the screen are cheap.

Best,

Clark