[swift-evolution] API Guidelines Update

Fri Feb 19 18:37:52 CST 2016

> On Feb 19, 2016, at 10:39 AM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 
> 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)

As I think you’ve said previously, it’s probably just a case where people (including me) need to get used to the idiom. There is a huge leap from:

a.stringByTrimmingCharactersInSet(b)
to:
a.trimming(b)

A couple of cognitive crutches that people have depended on are gone. 

There are things that make “-ing” function names more of an adjustment for some people, I think:

- It’s an idiom (if that’s the right word) for function naming that a lot of people haven’t been exposed to before.

- The expression at the call-site is grammatical, but perhaps not common usage, so people might still have to stop and think about what the function is doing until they get used to it.

- Though not a problem unique to “-ing”s, the function's primary purpose is to return something, but the function name by itself doesn’t reflect that (though the full expression at the call site does).

None of these are necessarily flaws, just things that people react to. So it might be reasonable to conclude there isn’t actually a problem. ;-)

> ? Are they hard to read?

In the limited sense of being unfamiliar usage for some people. It doesn’t seem grammatically awkward to me.

> Is it hard to arrive at these names, somehow?

Not IMO.

> Are the guidelines simply not clear enough about the procedure for
> producing names mutating/non-mutating pairs?

I think the people who have raised concerns are reacting to the aesthetics of particular examples and not to the difficultly of using the naming conventions.

>  Is it too easy to confuse that part of the guidelines with the general direction regarding methods with/without side-effects?

Without the examples, I think it might be confusing because you’re sorting through grammar rules. The examples provide the clarity.

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

It was a mis-statement there on my part anyway. I certainly didn’t mean I would resort to static methods just to avoid naming a function with “-ing"! (It hardly ever comes up.) I actually intended to say that in *“unioning”* cases — where there is a naming problem that is really problematic — I would be inclined to just punt and solve it with static methods or free functions. (And “let c = Set.union(a, b)" isn’t *that* bad, is it? ;-))

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

FWIW, that talk spurred me to totally rewrite one application from the ground up, and the results have been fantastic.

—CK

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