On 2010-02-03 18:01 PM, Steven D'Aprano wrote:
On Wed, 03 Feb 2010 16:38:21 -0600, Robert Kern wrote:
class.method(name, count)
Obviously? I don't know about that. Being told that "count" is an int
doesn't really help me -- it's obvious just from the name. In a well-
written API, what else could it be?
A bool. As in telling the method whether or not it should count
something.
Ha ha, good point. I question that this is a well-written API: such flags
to change the behaviour of a function/method are generally poor design.
If method behaves differently depending on whether or not you want it to
count something, then it is usually better design to have two methods,
one that counts and one that doesn't.
I prefer Guido's formulation (which, naturally, I can't find a direct quote for
right now): if you expect that a boolean argument is only going to take
*literal* True or False, then it should be split into two functions. There is a
use case for a boolean argument like this when you can expect to pass around a
variable between multiple functions.
Of course, this also might be the private API that the public API (with two
distinct methods for each case) uses internally in order to avoid code
duplication. Private APIs need to be documented, too.
In any case, yes, the weakness of naming conventions is that there are
always odd-corner cases of natural language. Perhaps `name` is also a
flag telling the method whether or not to name something.
But then, one can write crappy APIs in any language.
Well, I'm not trying to make Paul's point that other languages are better in
this regard. I think that type documentation is quite helpful, but requiring
static type declaration to get that documentation is an undesirable tradeoff for
most of the code that I want to write. I do think it is worthwhile to recognize
that the tradeoff does cut the other way, too. It just so happens that Python
has docstrings and argument annotations to document argument types without the
burden of static typing.
Not all good, clean APIs are always going to have argument names that clearly
inform the kind of type it expects. And what an author thinks is obviously
deducible while writing the API is often quite different from what a new user
thinks is obvious. There isn't much reason to place that cognitive burden on the
(many) readers of the code when the (single) author can put in a word or two
into the docstring (once) to describe what the parameter is expected to be.
Figuring out how to use an API to solve your real problem is hard enough without
having your brainpower nickled-and-dimed at every turn.
--
Robert Kern
"I have come to believe that the whole world is an enigma, a harmless enigma
that is made terrible by our own mad attempt to interpret it as though it had
an underlying truth."
-- Umberto Eco
--
http://mail.python.org/mailman/listinfo/python-list
