[swift-evolution] API Guidelines Update

Dave Abrahams dabrahams at apple.com
Thu Feb 18 12:02:11 CST 2016 

on Thu Feb 18 2016, Charles Kissinger <crk-AT-akkyra.com> wrote:

> Dave,
>
> My simple, non-linguist’s interpretation of the objections raised by
> Taras and others is that the “-ing” names might be strictly
> grammatical but they aren’t common usage, 

It is true that they are not common usage.

> and for that reason they often don’t feel right. To reference a famous
> movie quote, nobody would say: “Leave the gun, taking the
> cannolis”. It’s not how people speak or write.

I object strongly to that example; it doesn't at all have the form
presecribed by the guidelines.  To demonstrate how agitated this made me,
I'll confess that I just typed “proposed by the cannolis” before
correcting it! ;-)

You've used the present participle to form an adverbial phrase
(https://learningenglishgrammar.wordpress.com/adverbial-phrases-with-present-participles/)
modifying the verb “leave”—which also makes it part of the verb phrase.

The guidelines (without so much technical detail) suggest using “ing” to
form a participial phrase
(http://www.chompchomp.com/terms/participlephrase.htm) that functions as
an adjective modifying a noun (the receiver)—which also makes it part of
the noun phrase.


> Using your example: “Give me the list of all students, removing those
> who got As”, nobody would say that either. They would say: “Give me
> the list of students who didn’t get As.”
>
> I suppose another way of saying it is that these “-ing” forms sound
> stilted (with “unioning” being the poster child for that). 

Let's leave “unioning” out of it, please.  That is not the fault of the
“ing” guideline; it's the fault of some people's insistence on “verbing”
a perfectly good noun and failing to respect conventions for the domain
of sets.

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

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

> My own way of avoiding many of these “-ing”s is to use a static method
> for the non-mutating form:
>
> let z = Mytype.add(x, y)

Wow, that's truly unfortunate.

>
> —CK
>
>> On Feb 17, 2016, at 11:37 PM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
>> 
>> 
>> on Wed Feb 17 2016, Taras Zakharko <taras.zakharko-AT-uzh.ch> wrote:
>> 
>>>> On 18 Feb 2016, at 06:44, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
>>>> 
>>>>> 
>>>>> Also, you could infer "x.expanding..." alone to mean "x, *by*
>>>>> expanding..." or "*whether *x *is* expanding...", 
>>>> 
>>>> Only by adding words that aren't there.
>>> 
>>> I think what Jacob is trying to say is that an ‘-ing’ form does not
>>> have a clearly defined semantics in English. Depending on the
>>> construction, the meaning can differ. This creates potential
>>> confusion, as many people have pointed out earlier. Taking
>>> x.expanding() again, 
>> 
>> It's a bad example, because the guidelines say to prefer “ed” unless it
>> would be ungrammatical.  In this case,
>> 
>>      x.expanded()
>> 
>> is clearly grammatical, so you never end up here in the first place
>> 
>>> it is clear that guidelines intend an irrealis reading ‘if x were
>>> expanded, it would be’ or a resultative reading ‘x,after it has been
>>> expanded’. However, this is NOT a very typical reading associated with
>>> -ing forms.  In particular, other, more conventional readings include:
>>> 
>>> - converb construction (x is standing there, expanding)
>>> - atelic action/focus on a subprocess (x is expanding)
>>> - statement about a quality (x is expanding = x is of a quality that it is an expanding one)
>>> - question, by modifying prosody: (is x ) expanding?
>>> etc.
>>> 
>>> I believe that it is somewhat unfortunate that the guidelines
>>> (correctly, IMO) promote verbosity over luck of clarity and then at
>>> the same time introduce semantically obscure or outright weird notions
>>> based on the ‘-ing’ forms. Something like ‘x.havingAdded(e)’
>>> communicates the intent much better than ‘x.adding(e)’ (which reads
>>> like a notification), and yet more clear is ‘concatenate(x, e)’.
>> 
>> The problem is that if you use x.add/x.havingAdded as a standard
>> convention, you end up with gobs of methods that start with “having,”
>> which tends to break up the association between the mutating and
>> non-mutating forms.  We think that association is important.
>> 
>>> So going back to ‘adding words that aren’t there’ — by promoting this
>>> guideline rule, you are already doing this. 
>> 
>> Doing what?
>> 
>> (“this” without an antecedent; tsk, tsk --- yes, I'm well aware that
>> correcting a linguist's writing is very likely to backfire, but I
>> couldn't resist)
>> 
>>> But I digress. As a linguist, I am not very fond of this aspect of the
>>> guidelines, but if they are applied consistently, people will get used
>>> to them. Just don’t make a mistake and believe they are ‘grammatical’
>>> — they are not, 
>> 
>> That's quite a claim.  I previously understood you to be saying that the
>> forms weren't typical usage, but are you really saying that “Give me the
>> list of all students, removing those who got As” is ungrammatical?
>> 
>>> they are creating new conventional readings which are fairly untypical
>>> under normal language use.
>> 
>> Take out the "creating new" part and that is a completely separate issue
>> from grammaticality.  I would be very surprised if we were actually
>> inventing new grammar here, especially because these guidelines were
>> checked by a (different) linguist.  If you really mean that, I'll try to
>> put the two of you in touch so you can duke it out and we'll get a
>> determination.
>> 
>>> — Taras
>>> 
>>>> 
>>>>> so there might be some cases where it's easy to confuse Bool
>>>>> properties with non-Bools.
>>>> 
>>>> I don't get it; sorry...
>>>> 
>>>> -- 
>>>> -Dave
>>>> 
>>>> _______________________________________________
>>>> swift-evolution mailing list
>>>> swift-evolution at swift.org <mailto:swift-evolution at swift.org>
>>>> https://lists.swift.org/mailman/listinfo/swift-evolution <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

-- 
-Dave

More information about the swift-evolution mailing list