[swift-evolution] API Guidelines Update

[Dave Abrahams]

Hi again Charles,

I've been thinking about this response and I realized it might have left
you feeling that you hadn't been heard.  If that's the case I apologize,
and ask that you try again to make your point.  I *think* I understood
you, but of course it's impossible to be sure.

on Thu Feb 18 2016, Dave Abrahams <swift-evolution at swift.org> wrote:

> on Thu Feb 18 2016, Charles Kissinger <crk-AT-akkyra.com> wrote:
>
>> I’m not arguing the importance of this objection, just that I
>> understand it and think it’s valid.
>
> Though “ing” is a relatively uncommon usage, when used as
> prescribed IMO it reads pretty naturally, and is a good match for
> some important criteria:
>
> * it associates mutating and non-mutating forms
> * it's a syntactic match for method invocation, with the receiver on the
>   left
> * it preserves “fluency,” making code “read like English”
>
> If you have better ideas for how to satisfy these criteria, I'd be happy
> to hear them.
>
> We could debate the value of fluency in APIs, but I'd like to point out
> two things:

or three.

>
> 1. This API guidelines and renaming effort skewers many heretofore
>    sacred cows, which has been incredibly difficult to achieve
>    politically.  A year ago, the idea that we would ever apply “omit
>    needless words” to Cocoa was unthinkable.  IMO we've targeted the
>    cows that do definitive damage.
>
> 2. Fluency is itself deeply valued by many in our community, and has
>    influenced the design of core Swift at a fundamental level
>    (e.g. argument labels that are mandatory at the call site).
>
> 3. Properly applied (thus, no fair bringing up “unioning”), fluency does
>    no damage and in many cases improves clarity.  Connecting words like
>    prepositions can make the difference in implied meaning,
>    e.g. x.update(y) vs x.update(using: y).
>

-- 
-Dave