[Python-Dev] Unittest PEP do's and don'ts (BDFL pronouncement)

[Nick Coghlan]

Ben Finney wrote:
> The function name should say *all* that the function does, from the
> perspective of the caller.

I have to disagree with that (and I think you'll find plenty of other 
folks here will disagree as well). A good function names needs to have a 
few characters:
- serve as a mnemonic reminder as to what the function does for a 
programmer already familiar with the API
- allow a less familiar user to easily look it up in the API documentation
- be easy to remember to make the transition to familiarity with the API 
as rapid as possible

Wanting to say *everything* a function does in its name is an utterly 
unreasonable goal that leads to ridiculously long function names that 
nobody can remember.

Taking an existing function such as assertRaises and going "hey, we 
aren't using the return value from this, wouldn't it be really 
convenient if it told us the exact exception it actually caught?" 
doesn't cause any problems for existing code, and makes it much easier 
to write tests that need to check additional details about the exception 
that is raised (e.g. to check that the correct error code is captured 
and reported for things like OSError).

The essence of the function remains unchanged - you're still asserting 
that a particular exception is raised. Returning the actual exception 
object that was caught is merely a convenience that makes a lot of sense.

Try to think of it as being like adding a new optional argument to a 
function - just because the function now provides more flexibility is no 
reason to change it's name (e.g. when the key and reversed parameters 
were added to list.sort, the method name stayed the same). Taking an 
unused return value and making it meaningful is a similar kind of change.

Cheers,
Nick.




-- 
Nick Coghlan   |   ncoghlan at gmail.com   |   Brisbane, Australia
---------------------------------------------------------------
             http://www.boredomandlaziness.org