Naming future objects and their methods

[Jean-Michel Pichavant]

Stefan Schwarzer wrote:
> Hello,
>
> I wrote a `Connection` class that can be found at [1]. A
> `Connection` object has a method `put_bytes(data)` which
> returns a "future" [2]. The data will be sent asynchronously
> by a thread attached to the connection object.
>
> The future object returned by `put_bytes` has a `was_sent`
> method which will return `True` once the sender thread has
> actually sent the data via a socket call. An example might
> look like
>
>     put_result = connection.put_bytes(data)
>     if put_result.was_sent(timeout=1.0):
>         print "Data has been sent."
>     else:
>         print "Data hasn't been sent within one second."
>
> [snip]
>
> What do you think would be a "natural" way to name the
> future returned by `put_bytes` and possibly the `was_sent`
> method attached to it? Can you even come up with nice naming
> rules for futures and their methods? :-)
>
> [snip] Stefan
>   
Try to name your object after their goal or content instead of their type.
put_result is surely not a type but is still generic and refer more to 
the nature of the object.

Consider this :
aList = ['Ed', 'Will', 'Jane']
clients = ['Ed', 'Will', 'Jane']

The second form is better because it gives insights on the content and 
allow readers to know if you're doing what's intended.

So if you ever have an idea about what is sent through put_result, it 
would be better to name it with that.

If you don't know what is sent through the socket and you're handling it 
no matter the content, then "packet.sent(1.0)" sounds like a good 
solution as proposed by someone else.

Cheers,

JM