[swift-evolution] [Review] SE-0023 API Design Guidelines

[Paul Cantrell]

> On Jan 30, 2016, at 9:54 PM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
> 
> on Fri Jan 29 2016, Paul Cantrell <swift-evolution at swift.org> wrote:
> 
>> I do worry that these
>> proposed guidelines pack too much significance into the vagaries of
>> English grammar, which (as we’ve found out on this thread) is an
>> inconsistent and fickle friend. I’m personally in favor of charging
>> ahead with that quixotic venture nonetheless, but I do worry a bit
>> that the guidelines as stated are too narrowly stated in all the
>> places where grammar is involved.
> 
> Understood.  It would be nice to be able to say “just do what makes
> sense,” but the downside is that you lose regularity and you lose
> developer hours agonizing over trivia.  The downside of API guidelines
> is that they restrain you from doing what you want to do... and the
> upside is that they restain you from doing whatever you want to do. ;-)

An escape clause would help strike the balance: let the guidelines be as narrow as they are, but include a “guidelines are not laws” remark that gives teams permission to make carefully considered guideline overrides. This would prevent the “but it says so right here we must not deviate” vs. “but that injures clarity in our situation” argument within teams.

It seems to me that the first item under “Fundamentals,” maybe the first two, have a different order of importance than the rest of the document: “Clarity at the point of use is your most important goal. Clarity is more important than brevity.” That’s the Bill of Rights, as it were, and the rest of the guidelines are federal laws. Sometimes, in a particular situation, specific guidelines will come into conflict with clarity. You’ve written the guidelines to try to minimize that happening, but when it does, it’s clarity that should prevail.

…and I imagine we’d all agree on that, but having the guidelines explicitly say as much would prevent unnecessary agonizing.

Cheers,

Paul

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160131/0b531f59/attachment.html>