Design thought for callbacks

[Cem Karan]

On Feb 22, 2015, at 4:34 PM, Marko Rauhamaa <marko at pacujo.net> wrote:

> Cem Karan <cfkaran2 at gmail.com>:
> 
>> My goal is to make things as pythonic (whatever that means in this
>> case) and obvious as possible. Ideally, a novice can more or less
>> guess what will happen with my API without really having to read the
>> documentation on it.
> 
> If you try to shield your user from the complexities of asynchronous
> programming, you will only cause confusion. You will definitely need to
> document all nooks and crannies of the semantics of the callback API and
> your user will have to pay attention to every detail of your spec.
> 
> Your user, whether novice or an expert, will thank you for your
> unambiguous specification even if it is complicated.

Documentation is a given; it MUST be there.  That said, documenting something, but still making it surprising, is a bad idea.  For example, several people have been strongly against using a WeakSet to hold callbacks because they expect a library to hold onto callbacks.  If I chose not to do that, and used a WeakSet, then even if I documented it, it would still end up surprising people (and from the sound of it, more people would be surprised than not).

Thanks,
Cem Karan