[Bug 25388] Boolean arguments

https://www.w3.org/Bugs/Public/show_bug.cgi?id=25388

--- Comment #1 from Ryan Sleevi <sleevi@google.com> ---
(In reply to Anne from comment #0)
> Boolean arguments for methods are bad news. E.g. nobody ever remembers how
> addEventListener's third or XMLHttpRequest.prototype.open's third argument
> functions.
> 
> See http://c2.com/cgi/wiki?CodeSmellMetrics
> 
> It seems most of these methods could be designed to take a dictionary of
> sorts instead so the argument can be named and understood.

I can appreciate this feedback, however, it does not seem to be terribly useful
nor correct from a usability perspective.

Please note that the core API objects already take a dictionary of arguments -
the Algorithm dictionary (and it's sub-classes). This constitutes the bulk of
the parameters one might specify to a given operation.

Unless you're suggesting a dictionary-of-dictionaries, which itself seems a
code-smell, I'm not sure how you see this being an improvement.

In all of these methods, there is only a single boolean parameter - and it has
the exact same meaning across all methods - "extractable".

Possible interpretations of what you see as a "better" API include:

dictionary DeriveKeyParams {
  AlgorithmIdentifier algorithm;  // Really, "object"
  Key key;
  AlgorithmIdentifier derivedKeyType;  // Really, "object"
  boolean extractable;
  Sequence<KeyUsage> keyUsages;  // Instead of array
};

Promise<any> deriveKey(DeriveKeyParams params);

And it makes the calling convention go from
window.crypto.subtle.deriveKey({ alg }, key, { derived alg }, false, [
"encrypt" ]);

to
window.crypto.subtle.deriveKey({ algorithm: { alg }, key: key, derivedKeyType:
{ derived alg }, extractable: false, keyUsages: [ "encrypt" ]);

I cannot see how that's a better syntax - in part, it forgoes any possibility
of conciseness, because all the dictionary attributes cannot be minified or
elided.

While I can understand holy wars have been raged over positional versus named
arguments, that particular criticism doesn't seem to apply here, unless I'm
missing something fundamental that has changed in how Web APIs are written.

-- 
You are receiving this mail because:
You are on the CC list for the bug.

Received on Tuesday, 29 April 2014 00:09:33 UTC