Dreaming of new generation IDE

[Robert Kern]

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