API Guidelines Update

I'll have to think about it more. I'm trying to figure out why this seems
incomplete/confusing to me in some cases. "expandingTilde" doesn't "feel
like" a noun to me, but probably just because I'm not a linguist.

Also, you could infer "x.expanding..." alone to mean "x, *by* expanding..."
or "*whether *x *is* expanding...", so there might be some cases where it's
easy to confuse Bool properties with non-Bools.

···

On Wed, Feb 17, 2016 at 5:43 PM, Dave Abrahams <dabrahams@apple.com> wrote:

on Wed Feb 17 2016, Jacob Bandes-Storch <jtbandes-AT-gmail.com> wrote:

> On Wed, Feb 17, 2016 at 3:49 PM, Dave Abrahams via swift-evolution < > > swift-evolution@swift.org> wrote:
>
>>
>> on Wed Feb 17 2016, Jacob Bandes-Storch <swift-evolution@swift.org> > wrote:
>>
>> > Question about how to interpret/apply the guidelines:
>> >
>> > "[functions/methods] without side-effects should read as noun
>> phrases…"
>> > "Use the “ed/ing” rule to name the nonmutating counterpart of a
>> > mutating method…"
>> > "The names of other types, properties, variables, and constants
>> should
>> > read as nouns."
>> >
>> > Within these guidelines, how do we explain why
>> > *-stringByExpandingTildeInPath* becomes "var *expandingTildeInPath*"?
I'm
>> > wondering if the guidelines should clarify that the "ed/ing rule" may
>> apply
>> > to more than just nonmutating methods with mutating counterparts.
>>
>> Why should it?
>>
>
> Otherwise, it seems a case like this isn't really covered by the
guidelines.
>
>>
>> > I think that "var expandingTildeInPath" is probably the best choice
for
>> > this API, but I can't figure out how to reconcile it with the
guidelines
>> as
>> > written.
>>
>> The guidelines don't force you to spell it that way, but they allow it.
>>
>> “x, expanding the tilde in its path”
>>
>> is a noun phrase.
>>
>
> OK, I see. I guess what's confusing me is that I'm not sure why both the
> "ed/ing rule" and "read as noun" guidelines need to exist.

Because many methods are like:

        x.tracks(havingTitle: "foo")

That reads as a noun phrase, but is not an "ed" or "ing". The reason
for "ed"/"ing" is to maintain a name association between a method that
forms a verb phrase at the call site (the mutating one) and a method
that forms a noun phrase at the call site.

> Maybe it would be clearer if the sentence were something like "The names
of
> other types, properties, variables, and constants should read as nouns
*at
> the point of use (possibly including the receiver in the noun phrase)*."

I don't believe that's needed. The guidelines consistently and
repeatedly emphasize use sites, and I can't think of an invocation that
reads as a noun phrase with the receiver but doesn't without. Can you?

>
>>
>>
>> > Question about how to interpret/apply the guidelines:
>> >
>> > "[functions/methods] without side-effects should read as noun
>> phrases…"
>> > "Use the “ed/ing” rule to name the nonmutating counterpart of a
>> > mutating method…"
>> > "The names of other types, properties, variables, and constants
>> should
>> > read as nouns."
>> >
>> > Within these guidelines, how do we explain why
>> > *-stringByExpandingTildeInPath* becomes "var *expandingTildeInPath*"?
I'm
>> > wondering if the guidelines should clarify that the "ed/ing rule" may
>> apply
>> > to more than just nonmutating methods with mutating counterparts.
>>
>> Why should it?
>>
>
> Otherwise, it seems a case like this isn't really covered by the
guidelines.
>
>>
>> > I think that "var expandingTildeInPath" is probably the best choice
for
>> > this API, but I can't figure out how to reconcile it with the
guidelines
>> as
>> > written.
>>
>> The guidelines don't force you to spell it that way, but they allow it.
>>
>> “x, expanding the tilde in its path”
>>
>> is a noun phrase.
>>
>
> OK, I see. I guess what's confusing me is that I'm not sure why both the
> "ed/ing rule" and "read as noun" guidelines need to exist.

Because many methods are like:

        x.tracks(havingTitle: "foo")

That reads as a noun phrase, but is not an "ed" or "ing". The reason
for "ed"/"ing" is to maintain a name association between a method that
forms a verb phrase at the call site (the mutating one) and a method
that forms a noun phrase at the call site.

> Maybe it would be clearer if the sentence were something like "The names
of
> other types, properties, variables, and constants should read as nouns
*at
> the point of use (possibly including the receiver in the noun phrase)*."

I don't believe that's needed. The guidelines consistently and
repeatedly emphasize use sites, and I can't think of an invocation that
reads as a noun phrase with the receiver but doesn't without. Can you?

I'll have to think about it more. I'm trying to figure out why this seems
incomplete/confusing to me in some cases. "expandingTilde" doesn't "feel
like" a noun to me, but probably just because I'm not a linguist.

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.

so there might be some cases where it's easy to confuse Bool
properties with non-Bools.

I don't get it; sorry...

···

on Wed Feb 17 2016, Jacob Bandes-Storch <swift-evolution@swift.org> wrote:

On Wed, Feb 17, 2016 at 5:43 PM, Dave Abrahams <dabrahams@apple.com> wrote:

on Wed Feb 17 2016, Jacob Bandes-Storch <jtbandes-AT-gmail.com> wrote:
> On Wed, Feb 17, 2016 at 3:49 PM, Dave Abrahams via swift-evolution < >> > swift-evolution@swift.org> wrote:
>> on Wed Feb 17 2016, Jacob Bandes-Storch <swift-evolution@swift.org> >> wrote:

--
-Dave

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

So going back to ‘adding words that aren’t there’ — by promoting this guideline rule, you are already doing this. 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, they are creating new conventional readings which are fairly untypical under normal language use.

— Taras

···

On 18 Feb 2016, at 06:44, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

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@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

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.

···

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@swift.org> wrote:

— 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@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

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

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). I’m not arguing the importance of this objection, just that I understand it and think it’s valid.

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)

—CK

···

On Feb 17, 2016, at 11:37 PM, Dave Abrahams via swift-evolution <swift-evolution@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@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@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

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

I agree, the -ed forms are much more clear than the -ing forms.

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.

I understand the predicament. But how far would you go to keep it? See the SetAlgebra thread.

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)

Yeah, linguists are often misunderstood :) Just so that you know — most linguists don’t care that much for the arbitrary prescriptive school grammar rules (btw., the antecedent is “adding words that aren’t there”).

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?

Thats why I put “grammatical” in quotes. Grammar is the case of extreme conventionalisation/optimisation of message encoding, but its the actual use is what is important here. Of course, these forms are perfectly grammatical in the narrow sense in that they follow the conventional rules of morphology/syntax of English. What I was trying to say that they do not necessarily follow “grammar” in the broad sense, which includes semantics and maybe even pragmatics. So sure, if one accepts that conventional association between form and meaning is part of the grammar, one could claim that the -ing rule is ‘inventing new grammar”, albeit of course not under the common understanding of grammaticality. In the end, language is defined by its use, and arguing that something is grammatical when it can’t be reliably interpreted by the recipient catapults us into the realm of obscure academics (which is very interesting in itself, but probably not relevant to the discussion at hand).

(And yes, I know that a run-of-the mill Chomskian linguist would lash at me at this point, but unfortunately, I am not a Chomsky believer)

I think, the ultimate question boils down to whether its possible to find a better solution. This is of course conditional on your goals, which are ultimately subjective. For instance, you state that it is important for you not to break the association between mutating and non-mutating methods. Then the solution you propose is certainly quite logical and understandable, even if its a bit unfortunate from the language use point of view. I feel like it can lead to quite awkward solutions at times (see the SetAlgebra thread).

Personally, I would have preferred either relaxing the connection between mutating and non-mutating methods (but its a non-go according to your goals) or implement non-mutating methods as class methods (effectively constructors), e.g. string.sort vs String.sort(string), array.add vs Array.add(array, element) etc. But this of course results in a lot of repetition, so its not optimal either.

In the end, its important to pick something and stick to it. We can discuss this back and forth without end (and btw, its very encouraging that you are willing to discuss these things to begin with), but its not much use if the discussion does not result in anything constructive. You’ve made your decision, people in general seem ok with it, and now the question is about applying it in a sensible way. Which for me at least implies thinking twice before using an -ing form.

Best,

Taras

···

On 18 Feb 2016, at 08:37, Dave Abrahams <dabrahams@apple.com> wrote:
on Wed Feb 17 2016, Taras Zakharko <taras.zakharko-AT-uzh.ch <http://taras.zakharko-at-uzh.ch/&gt;&gt; wrote:

On 18 Feb 2016, at 06:44, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

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@swift.org <mailto:swift-evolution@swift.org> <mailto:swift-evolution@swift.org <mailto:swift-evolution@swift.org>>
https://lists.swift.org/mailman/listinfo/swift-evolution <https://lists.swift.org/mailman/listinfo/swift-evolution&gt;

--
-Dave

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

I agree, the -ed forms are much more clear than the -ing forms.

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.

I understand the predicament. But how far would you go to keep it? See
the SetAlgebra thread.

Not as far as that, personally. IMO that should fall under the “Use
terminology well” clause.

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)

Yeah, linguists are often misunderstood :) Just so that you know —
most linguists don’t care that much for the arbitrary prescriptive
school grammar rules (btw., the antecedent is “adding words that
aren’t there”).

What words did I add that weren't there?

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?

Thats why I put “grammatical” in quotes. Grammar is the case of
extreme conventionalisation/optimisation of message encoding, but its
the actual use is what is important here. Of course, these forms are
perfectly grammatical in the narrow sense in that they follow the
conventional rules of morphology/syntax of English. What I was trying
to say that they do not necessarily follow “grammar” in the broad
sense, which includes semantics and maybe even pragmatics. So sure, if
one accepts that conventional association between form and meaning is
part of the grammar, one could claim that the -ing rule is ‘inventing
new grammar”, albeit of course not under the common understanding of
grammaticality. In the end, language is defined by its use, and
arguing that something is grammatical when it can’t be reliably
interpreted by the recipient catapults us into the realm of obscure
academics (which is very interesting in itself, but probably not
relevant to the discussion at hand).

(And yes, I know that a run-of-the mill Chomskian linguist would lash
at me at this point, but unfortunately, I am not a Chomsky believer)

This is all way beyond me. I think most people understand how these
things are supposed to work from the examples.

I think, the ultimate question boils down to whether its possible to
find a better solution. This is of course conditional on your goals,
which are ultimately subjective. For instance, you state that it is
important for you not to break the association between mutating and
non-mutating methods. Then the solution you propose is certainly quite
logical and understandable, even if its a bit unfortunate from the
language use point of view. I feel like it can lead to quite awkward
solutions at times (see the SetAlgebra thread).

That mess is not the fault of the guidelines, which provide enough
leeway to make sensible and natural choices.

Personally, I would have preferred either relaxing the connection
between mutating and non-mutating methods (but its a non-go according
to your goals) or implement non-mutating methods as class methods
(effectively constructors), e.g. string.sort vs String.sort(string),
array.add vs Array.add(array, element) etc. But this of course results
in a lot of repetition, so its not optimal either.

In the end, its important to pick something and stick to it. We can
discuss this back and forth without end (and btw, its very encouraging
that you are willing to discuss these things to begin with), but its
not much use if the discussion does not result in anything
constructive. You’ve made your decision, people in general seem ok
with it, and now the question is about applying it in a sensible
way. Which for me at least implies thinking twice before using an -ing
form.

I hope you'll think twice about all naming choices.

···

on Thu Feb 18 2016, Taras Zakharko <taras.zakharko-AT-uzh.ch> wrote:

On 18 Feb 2016, at 08:37, Dave Abrahams <dabrahams@apple.com> wrote:
on Wed Feb 17 2016, Taras Zakharko <taras.zakharko-AT-uzh.ch <http://taras.zakharko-at-uzh.ch/&gt;&gt; wrote:

On 18 Feb 2016, at 06:44, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

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@swift.org <mailto:swift-evolution@swift.org>
<mailto:swift-evolution@swift.org
<mailto:swift-evolution@swift.org>>
https://lists.swift.org/mailman/listinfo/swift-evolution
<https://lists.swift.org/mailman/listinfo/swift-evolution&gt;
<https://lists.swift.org/mailman/listinfo/swift-evolution
<https://lists.swift.org/mailman/listinfo/swift-evolution&gt;&gt;

--
-Dave

--
-Dave

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.

···

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

—CK

On Feb 17, 2016, at 11:37 PM, Dave Abrahams via swift-evolution <swift-evolution@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@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@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

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.

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.

···

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

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

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

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

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”, I’ll admit that some of my opinions about common practice in object oriented programming, and the entire OO paradigm itself, are not mainstream.

···

On Feb 18, 2016, at 4:30 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

on Thu Feb 18 2016, Dave Abrahams <swift-evolution@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@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

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, Charles Kissinger <swift-evolution@swift.org> wrote:

On Feb 18, 2016, at 4:30 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

on Thu Feb 18 2016, Dave Abrahams <swift-evolution@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@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

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 Feb 19, 2016, at 10:39 AM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:
on Thu Feb 18 2016, Charles Kissinger <swift-evolution@swift.org> wrote:

On Feb 18, 2016, at 4:30 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

on Thu Feb 18 2016, Dave Abrahams <swift-evolution@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@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

Neither really feel right - I am not against long names, but sometimes people have long names because
they are unfocused and the API to a class/type has too many unfocused methods on it.
Then it gets applied to other classes/types with less methods since it is more consistent with the naming
of the class/types that they have already completed.

Whereas “ing”/“ed” is against all the naming conventions (closer to opposite of what was acceptable) of
any development environment I have worked in the last 30 years. It is not that I don’t accept and embrace
change — if that were the case I would not be constantly learning.

“ing” (the worst of the two) to me infers that something is in progress… i.e. “process”.isRunning or “process”.running.

“ed” (least worst) to me infers that you are querying the state of something “process”.completed.

Both mutable and immutable execute and complete and results are either returned or applied.

I have generally (maybe always) kept things that “mutate” separate from things that don’t (unless I am working in a
system where immutable vs mutable never entered the mind of the developer). It feels more focused. In most cases
it is fairly easy to do, and cleaner. I don’t know if there is some performance reason why the mixing of the
two (across the whole API) is more advantageous. But even in that case it will constantly be nagging me, and
giving me the feeling that something went horribly wrong and it is something that needs to be looked at to
see if it needs to be refactored and simplified.

So for me it is not just that it is grammatically awkward, it will constantly be giving me a feeling that something went
horribly wrong and that it needs to be looked at again to see if it could have been done in a more simplified
and focused way.

···

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.

Neither really feel right - I am not against long names, but sometimes
people have long names because they are unfocused and the API to a
class/type has too many unfocused methods on it. Then it gets applied
to other classes/types with less methods since it is more consistent
with the naming of the class/types that they have already completed.

Whereas “ing”/“ed”

Wrong order; “ed”/“ing” please! ;-)

is against all the naming conventions (closer to
opposite of what was acceptable) of any development environment I have
worked in the last 30 years. It is not that I don’t accept and
embrace change — if that were the case I would not be constantly
learning.

“ing” (the worst of the two) to me infers that something is in
progress… i.e. “process”.isRunning or “process”.running.

Ah; I understand. The guidelines specify that for this purpose the
above should read like an assertion about the receiver,
e.g. “process.isRunning,” and heretofore Cocoa has always used
“process.running.” So I can see why it might be hard to re-train your
instincts on this.

“ed” (least worst) to me infers that you are querying the state of
something “process”.completed.

Same applies here.

Both mutable and immutable execute and complete and results are either
returned or applied.

I have generally (maybe always) kept things that “mutate” separate
from things that don’t (unless I am working in a system where
immutable vs mutable never entered the mind of the developer). It
feels more focused. In most cases it is fairly easy to do, and
cleaner. I don’t know if there is some performance reason why the
mixing of the two (across the whole API) is more advantageous.

Let's just consider sets, for example. If an in-place
intersection suits what you're trying to do, then

  x.intersectWith(y) // or however you spell it; mutating

can avoid doing any new allocations and most of the data copying that
would otherwise be result from

  x = x.intersection(y) // or however you spell it; non-mutating

It's certainly possible to argue that sets should only have mutating
operations, but that seems like a really harsh break with tradition, and
would make combining sets that are immutable due to “let” bindings quite
awkward.

But even in that case it will constantly be nagging me, and giving me
the feeling that something went horribly wrong and it is something
that needs to be looked at to see if it needs to be refactored and
simplified.

So for me it is not just that it is grammatically awkward, it will
constantly be giving me a feeling that something went horribly wrong
and that it needs to be looked at again to see if it could have been
done in a more simplified and focused way.

Hmm, I understand that... But maybe you should watch
WWDC15 - Videos - Apple Developer (again). We want
programmers to be really comfortable with mutation. The premise behind
our emphasis on value types is that the real underlying problem that
drives people to create immutable data structures is usually implicit
sharing, rather than mutation.

···

on Fri Feb 19 2016, Craig Cruden <swift-evolution@swift.org> wrote:

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.

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

Neither really feel right - I am not against long names, but sometimes people have long names because they are unfocused and the API to a class/type has too many unfocused methods on it. Then it gets applied to other classes/types with less methods since it is more consistent with the naming of the class/types that they have already completed.

Whereas “ing”/“ed” is against all the naming conventions (closer to opposite of what was acceptable) of any development environment I have worked in the last 30 years.

Hi Craig,

I just haven’t been able to come up with a convention that meets Dave’s requirements and is consistently better. The best “-ing” alternative to my eye is “with-":

s.expandTilde() // mutating
let t = s.withExpandedTilde() // non-mutating

x.append(y)
let z = x.withAppended(y) // Meh

a.trim(.whitespaceAndNewlines)
let b = a.withTrimmed(.whitespaceAndNewlines)

—CK

···

On Feb 19, 2016, at 5:20 PM, Craig Cruden <ccruden@novafore.com> wrote:

It is not that I don’t accept and embrace
change — if that were the case I would not be constantly learning.

“ing” (the worst of the two) to me infers that something is in progress… i.e. “process”.isRunning or “process”.running.

“ed” (least worst) to me infers that you are querying the state of something “process”.completed.

Both mutable and immutable execute and complete and results are either returned or applied.

I have generally (maybe always) kept things that “mutate” separate from things that don’t (unless I am working in a
system where immutable vs mutable never entered the mind of the developer). It feels more focused. In most cases
it is fairly easy to do, and cleaner. I don’t know if there is some performance reason why the mixing of the
two (across the whole API) is more advantageous. But even in that case it will constantly be nagging me, and
giving me the feeling that something went horribly wrong and it is something that needs to be looked at to
see if it needs to be refactored and simplified.

So for me it is not just that it is grammatically awkward, it will constantly be giving me a feeling that something went
horribly wrong and that it needs to be looked at again to see if it could have been done in a more simplified
and focused way.

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.

I'll second that. "a.withTrimmed(.whitespaceAndNewlines)" makes no sense to me, i.e. the name "withTrimmed" is hurting comprehension. I tried to figure out why this is and eventually decided my brain was grouping it as "a with [trimmed whitespace]", as if "trimmed whitespace" were a thing. "havingTrimmed" would have been okay (a participle form), but feels clunky.

In case it's been lost in all the discussion, the -ing/-ed rule is essentially the rule Objective-C uses, minus the noun labels for the return value and types and the word "by". It's definitely very different grammatically from most other API guidelines, but so are Objective-C's guidelines.

Jordan

···

On Feb 20, 2016, at 13:26, Charles Kissinger via swift-evolution <swift-evolution@swift.org> wrote:

On Feb 19, 2016, at 5:20 PM, Craig Cruden <ccruden@novafore.com <mailto:ccruden@novafore.com>> wrote:

Neither really feel right - I am not against long names, but sometimes people have long names because they are unfocused and the API to a class/type has too many unfocused methods on it. Then it gets applied to other classes/types with less methods since it is more consistent with the naming of the class/types that they have already completed.

Whereas “ing”/“ed” is against all the naming conventions (closer to opposite of what was acceptable) of any development environment I have worked in the last 30 years.

Hi Craig,

I just haven’t been able to come up with a convention that meets Dave’s requirements and is consistently better. The best “-ing” alternative to my eye is “with-":

s.expandTilde() // mutating
let t = s.withExpandedTilde() // non-mutating

x.append(y)
let z = x.withAppended(y) // Meh

a.trim(.whitespaceAndNewlines)
let b = a.withTrimmed(.whitespaceAndNewlines)

Sure, but I'd actually argue that the noun-labels in ObjC are what actually provide the context of the non-mutating nature of the function. The -ed/-ing suffixes are a by-product of the preceding noun-phrase and/or trailing preposition.

stringByTrimmingCharactersInSet(_:)

We are taking information about the returned data out of the function name and assuming that the return type makes up for it.

trimming(_:)

For a string-type, that may be ok, but I'd argue that `trimming` is significantly more ambiguous that the ObjC version. There is no reasonable assumption that `stringByTrimmingCharactersInSet` would ever mutate the caller. However, `trimming` carries no such implication _unless_ you are well versed in the API guidelines, and even then, I'd still argue that your confidence level between the two versions is not equal.

A counter example for -ing usage: if we have a streaming-type and `trimming` is actually the process for continually removing those characters from the stream. The likely implementation of this is going to be a mutating function that fires events, or maybe it's a promise-like API that wraps the event handling differently. The corollary is that `trim` would actually be the one that produces no side-effects as it would be able to give a snapshot of the current state of a trimmed stream.

I think we are opening ourselves up to the potential of many confusing APIs when an -ed/-ing form of a function name is an appropriate candidate with the opposite meaning that the guidelines set out.

The -ed/-ing suffix choice doesn't seem outright bad, but it does seem to be "death by paper cuts" bad, at least to me. The guidelines are already a bit complicated in this area. Also, like others, I find the -ing suffix to imply a state of work to be done that will be completed later or cover an extended amount of time; mutation has no bearing on the implementation choice here.

Side note: the guidelines are also unintentionally narrow: "Use the “ed/ing” rule to name the nonmutating counterpart of a mutating method."

We should *always* be following this pattern regardless of the existence of a nonmutating counterpart. Otherwise, if you implement just a non-mutating function for sorting without the counterpart, you need to use a noun-phrase, like `sortBy`. Then if you later add a mutating version, you need to rename the `sortBy` to `sorted`. That seems like the wrong outcome of the guidelines.

-David

···

On Feb 22, 2016, at 11:02 AM, Jordan Rose via swift-evolution <swift-evolution@swift.org> wrote:

In case it's been lost in all the discussion, the -ing/-ed rule is essentially the rule Objective-C uses, minus the noun labels for the return value and types and the word "by". It's definitely very different grammatically from most other API guidelines, but so are Objective-C's guidelines.

In case it's been lost in all the discussion, the -ing/-ed rule is
essentially the rule Objective-C uses, minus the noun labels for the
return value and types and the word "by". It's definitely very
different grammatically from most other API guidelines, but so are
Objective-C's guidelines.

Sure, but I'd actually argue that the noun-labels in ObjC are what
actually provide the context of the non-mutating nature of the
function.

I disagree with that assertion. The nouns tell you what type is going
to be returned and what type is being passed, not whether there will be
mutation to the receiver.

The -ed/-ing suffixes are a by-product of the preceding noun-phrase
and/or trailing preposition.

stringByTrimmingCharactersInSet(_:)

We are taking information about the returned data out of the function
name and assuming that the return type makes up for it.

The return type and context, yes.

trimming(_:)

For a string-type, that may be ok, but I'd argue that `trimming` is
significantly more ambiguous that the ObjC version. There is no
reasonable assumption that `stringByTrimmingCharactersInSet` would
ever mutate the caller. However, `trimming` carries no such
implication _unless_ you are well versed in the API guidelines,

I disagree with that assertion. We didn't invent that usage out of thin
air; it's based on regular English usage. Neither of these names really
directly addresses mutation at all; to do that you'd have to append
"WithoutChangingSelf" or something.

It seems like you may (quite reasonably) associate having a return value
with being non-mutating, and you may be making the conclusion that
removing information about the return type removes any implication that
there *is* a returned value. But there are still lots of clues left
about that:

* the call forms a noun phrase, therefore must be non-side-effectful, so
  to be useful must return something.
* unused result warnings ensure that the fact that it returns a value is
  quite visible at the call site.

and even then, I'd still argue that your confidence level between the
two versions is not equal.

I understand that you may be less confident with APIs written according
to the new guidelines.

A counter example for -ing usage: if we have a streaming-type and
`trimming` is actually the process for continually removing those
characters from the stream. The likely implementation of this is going
to be a mutating function that fires events, or maybe it's a
promise-like API that wraps the event handling differently. The
corollary is that `trim` would actually be the one that produces no
side-effects as it would be able to give a snapshot of the current
state of a trimmed stream.

I don't believe this is actually a confusable scenario; please show us
what that code looks like.

I think we are opening ourselves up to the potential of many confusing
APIs when an -ed/-ing form of a function name is an appropriate
candidate with the opposite meaning that the guidelines set out.

The -ed/-ing suffix choice doesn't seem outright bad, but it does seem
to be "death by paper cuts" bad, at least to me. The guidelines are
already a bit complicated in this area. Also, like others, I find the
-ing suffix to imply a state of work to be done that will be completed
later or cover an extended amount of time; mutation has no bearing on
the implementation choice here.

Side note: the guidelines are also unintentionally narrow: "Use the
“ed/ing” rule to name the nonmutating counterpart of a mutating
method."

We should *always* be following this pattern regardless of the
existence of a nonmutating counterpart. Otherwise, if you implement
just a non-mutating function for sorting without the counterpart, you
need to use a noun-phrase, like `sortBy`. Then if you later add a
mutating version, you need to rename the `sortBy` to `sorted`. That
seems like the wrong outcome of the guidelines.

I think you're confused: `sortBy(x)`—or more properly, `sort(by:
x)`—isn't a noun-phrase; it's an imperative verb phrase, so it would be
an ineligible form for a nonmutating method call.

···

on Wed Feb 24 2016, David Owens II <swift-evolution@swift.org> wrote:

On Feb 22, 2016, at 11:02 AM, Jordan Rose via swift-evolution >> <swift-evolution@swift.org> wrote:

--
-Dave

In case it's been lost in all the discussion, the -ing/-ed rule is
essentially the rule Objective-C uses, minus the noun labels for the
return value and types and the word "by". It's definitely very
different grammatically from most other API guidelines, but so are
Objective-C's guidelines.

Sure, but I'd actually argue that the noun-labels in ObjC are what
actually provide the context of the non-mutating nature of the
function.

I disagree with that assertion. The nouns tell you what type is going
to be returned and what type is being passed, not whether there will be
mutation to the receiver.

For the Cocoa value types, I agree with DavidO that a return-type noun reliably distinguishes mutation from non-mutation, and is a better-than-50% indicator for methods on other types as well. This is part of the established Cocoa convention and is (sort of) called out <Naming Methods; in the existing (sparse) naming guidelines.

However, I don't think that's that much less subtle than the -ing ending. It's a different cue but not one that's really any more or less noticeable. (Evidence: DaveA did not know it or infer it despite driving this effort, i.e. getting plenty of exposure to many different APIs.)

(The participle ending for nullary methods or properties may be a little more subtle, especially for non-English speakers..)

A counter example for -ing usage: if we have a streaming-type and `trimming` is actually the process for continually removing those characters from the stream. The likely implementation of this is going to be a mutating function that fires events, or maybe it's a promise-like API that wraps the event handling differently. The corollary is that `trim` would actually be the one that produces no side-effects as it would be able to give a snapshot of the current state of a trimmed stream.

I can't actually picture this API. 'trimming' and 'trim' don't seem to follow the naming conventions for the operations you've described. Can you write it out?

Side note: the guidelines are also unintentionally narrow: "Use the “ed/ing” rule to name the nonmutating counterpart of a mutating method."

We should *always* be following this pattern regardless of the existence of a nonmutating counterpart. Otherwise, if you implement just a non-mutating function for sorting without the counterpart, you need to use a noun-phrase, like `sortBy`. Then if you later add a mutating version, you need to rename the `sortBy` to `sorted`. That seems like the wrong outcome of the guidelines.

This I definitely agree with. If you have a non-mutating member that returns the same type as the receiver, it should be named as if there could be an in-place version added later.

Jordan

···

On Feb 24, 2016, at 11:25, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:
on Wed Feb 24 2016, David Owens II <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

On Feb 22, 2016, at 11:02 AM, Jordan Rose via swift-evolution >>> <swift-evolution@swift.org> wrote:

In case it's been lost in all the discussion, the -ing/-ed rule is
essentially the rule Objective-C uses, minus the noun labels for the
return value and types and the word "by". It's definitely very
different grammatically from most other API guidelines, but so are
Objective-C's guidelines.

Sure, but I'd actually argue that the noun-labels in ObjC are what
actually provide the context of the non-mutating nature of the
function.

I disagree with that assertion. The nouns tell you what type is going
to be returned and what type is being passed, not whether there will be
mutation to the receiver.

The noun tells you the object that will be worked with.

`stringByTrimmingCharactersInSet(_:)` - return a string by trimming characters in set

`trimCharactersInSet(_:)`, `trim(_:)`, and `trimming(_:)` all read: return myself by trimming characters in set; there is no noun, so it is implied that it's the caller of the function.

The first two guidelines already captures this sentiment as well:

  1. "Those without side-effects should read as noun phrases".
  2. "Those with side-effects should read as imperative verb phrases."

I think we are opening ourselves up to the potential of many confusing
APIs when an -ed/-ing form of a function name is an appropriate
candidate with the opposite meaning that the guidelines set out.

The -ed/-ing suffix choice doesn't seem outright bad, but it does seem
to be "death by paper cuts" bad, at least to me. The guidelines are
already a bit complicated in this area. Also, like others, I find the
-ing suffix to imply a state of work to be done that will be completed
later or cover an extended amount of time; mutation has no bearing on
the implementation choice here.

Side note: the guidelines are also unintentionally narrow: "Use the
“ed/ing” rule to name the nonmutating counterpart of a mutating
method."

We should *always* be following this pattern regardless of the
existence of a nonmutating counterpart. Otherwise, if you implement
just a non-mutating function for sorting without the counterpart, you
need to use a noun-phrase, like `sortBy`. Then if you later add a
mutating version, you need to rename the `sortBy` to `sorted`. That
seems like the wrong outcome of the guidelines.

I think you're confused: `sortBy(x)`—or more properly, `sort(by:
x)`—isn't a noun-phrase; it's an imperative verb phrase, so it would be
an ineligible form for a nonmutating method call.

I think you threw out the baby with the bathwater because of a technicality there. Let's try again.

The stages of an API development process might look like this:

version 1: "Those without side-effects should read as noun phrases"

func contentsOf(filter:) -> Self // returns a copy

version 2: "Those with side-effects should read as imperative verb phrases"

func contentsOf(filter:) -> Self // returns a copy
mutating func filter(by:) // honestly, I'm not sure where the preposition debate has landed...

version 3, bug comes in that the API doesn't meet the guidelines.

func filtered(by:) -> Self // returns a copy
mutating func filter(by:)

Unless I'm misunderstanding the guidelines, this is the natural progression of the API (minus the `by` preposition, which is irrelevant to this discussion).

In my opinion, the guidelines should not lead us down breaking API changes as the API evolves. The entire -ed/-ing confuses the entire section, and requires future knowledge of what the future API will look like beforehand. This circles back to my first point about the noun actually serving as more information that the type.

-David

···

On Feb 24, 2016, at 11:25 AM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:
on Wed Feb 24 2016, David Owens II <swift-evolution@swift.org> wrote:

On Feb 22, 2016, at 11:02 AM, Jordan Rose via swift-evolution >>> <swift-evolution@swift.org> wrote: