Design thought for callbacks
Cem Karan
cfkaran2 at gmail.com
Sun Feb 22 17:09:01 EST 2015
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
More information about the Python-list
mailing list