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

[Dave Abrahams]

on Sun Jan 31 2016, Paul Cantrell <cantrell-AT-pobox.com> wrote:

>> 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.

I'm wary of doing that.  Having worked with these guidelines for months,
my guess is that 90% of the time one thinks one can't conform to the
guidelines without losing clarity, one just hasn't thought of how to do
it yet.  If you're let off the hook too early, you end up with avoidable
non-uniformity in the name of clarity.  Do you really think people can't
infer priorities from the structure of the document and the permission
to bend from the fact that they're called “guidelines?”

-- 
-Dave