[swift-evolution] API Guidelines Update

[Dave Abrahams]

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

>> On Feb 18, 2016, at 4:30 PM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
>> 
>> 
>> 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.
>
> Hi Dave,
>
> The only motivation for my post was that I thought the discussion
> around “-ing” method names had gotten complex and somewhat
> contentious, and it seemed like no one had successfully, succinctly
> communicated the reason for the unease some of us have with those
> names.
>
> I don’t think I succeeded any better than anyone else, but in
> retrospect, there really isn’t any value in continuing to argue the
> merits unless someone can suggest something better. (Which I
> can’t. :-))

Well, I'd still like to understand the actual problem.  Leaving aside
the whole “Set mess,” do you see a problem with guidelines that lead to
pairs like:

    x.trim(.WhitespaceAndNewlines)
    y = z.trimming(.WhitespaceAndNewlines)

? Are they hard to read?  Is it hard to arrive at these names, somehow?
Are the guidelines simply not clear enough about the procedure for
producing names mutating/non-mutating pairs?  Is it too easy to confuse
that part of the guidelines with the general direction regarding methods
with/without side-effects?

> The fact that this one issue is the only one that anybody seems to
> have any remaining complaints about has to be a very good sign.  I
> think those of us on the outside do tend to forget that there has been
> much sacred cow slaughtering and other mayhem required to get to this
> point. :-)
>
> —CK
>
> P.S. And I cheerfully accept some mockery regarding the choices in my
> own personal “API guidelines”, 

Not at all.  I just think it's really sad that we've pushed you into
using such a verbose and cumbersome notation for things that should be
the simplest: non-mutating transformations.

> I’ll admit that some of my opinions about common practice in object
> oriented programming, and the entire OO paradigm itself, are not
> mainstream.

Join the club.  I remember someone gave a pretty cool talk at WWDC about
how OOP wasn't the be-all and end-all. ;-)

>> 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
>> 
>> _______________________________________________
>> swift-evolution mailing list
>> swift-evolution at swift.org
>> https://lists.swift.org/mailman/listinfo/swift-evolution
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-- 
-Dave