[Python-Dev] Unittest PEP do's and don'ts (BDFL pronouncement)
ncoghlan at gmail.com
Thu Jul 17 12:18:55 CEST 2008
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
- 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.
Nick Coghlan | ncoghlan at gmail.com | Brisbane, Australia
More information about the Python-Dev