API Guidelines Update

Evolution Discussion
1

I've updated the API guidelines document to account for the review
feedback and other issues. Please see
http://apple.github.io/swift-internals/api-design-guidelines/
(presentation view)
and
https://github.com/apple/swift-internals/blob/gh-pages/api-design-guidelines/index.md
(source and commit history)

···

--
-Dave

2

I like.

Minor grammar fix: Remove the comma in "declared only once, but used
repeatedly" in the first rule.

···

On Tue, Feb 16, 2016 at 9:31 PM, Dave Abrahams via swift-evolution < swift-evolution@swift.org> wrote:

I've updated the API guidelines document to account for the review
feedback and other issues. Please see
http://apple.github.io/swift-internals/api-design-guidelines/
(presentation view)
and

https://github.com/apple/swift-internals/blob/gh-pages/api-design-guidelines/index.md
(source and commit history)

--
-Dave

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

--
Trent Nadeau

3

Dave,

At one point there was discussion of special handling of prepositional phrases containing “of”, with the “of” being placed before the parenthesis rather than in the argument label. Was that left out of the guidelines deliberately or inadvertently (or did I miss it)?

—CK

···

On Feb 16, 2016, at 6:31 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

I've updated the API guidelines document to account for the review
feedback and other issues. Please see
http://apple.github.io/swift-internals/api-design-guidelines/
(presentation view)
and
https://github.com/apple/swift-internals/blob/gh-pages/api-design-guidelines/index.md
(source and commit history)

--
-Dave

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

4

Three places where you might have intended different wording:

"Prefer names of function and other methods that make use sites form grammatical English phrases.”
Should it be:
"Prefer method and function names that make use sites form grammatical English phrases.” ?

“Initializer and factory methods calls should form a phrase that does not include the first argument, e.g.”
Should it be:
“Initializer and factory method calls should form a phrase that does not include the first argument, e.g.” ?

“Label closure parameters and the tuple members where they appear in your API.”
Should it be:
“Label closure parameters and tuple members where they appear in your API.” ?

Also, there appears to be a repeated “the” here:
/// **`byteCount`** equal to the the number of maximally-aligned

—CK

···

On Feb 16, 2016, at 6:31 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

I've updated the API guidelines document to account for the review
feedback and other issues. Please see
http://apple.github.io/swift-internals/api-design-guidelines/
(presentation view)
and
https://github.com/apple/swift-internals/blob/gh-pages/api-design-guidelines/index.md
(source and commit history)

--
-Dave

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

5

Nice, I dig the changes.

Some wording wrinkles here and there, but I’m glad feedback from the community was incorporated.

Cheers,
— Radek

···

On 17 Feb 2016, at 03:31, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

I've updated the API guidelines document to account for the review
feedback and other issues. Please see
http://apple.github.io/swift-internals/api-design-guidelines/
(presentation view)
and
https://github.com/apple/swift-internals/blob/gh-pages/api-design-guidelines/index.md
(source and commit history)

--
-Dave

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

6

I like.

Minor grammar fix: Remove the comma in "declared only once, but used
repeatedly" in the first rule.

Thanks!

FYI, for the future, pull requests work great :-)

···

on Tue Feb 16 2016, Trent Nadeau <swift-evolution@swift.org> wrote:

On Tue, Feb 16, 2016 at 9:31 PM, Dave Abrahams via swift-evolution < > swift-evolution@swift.org> wrote:

I've updated the API guidelines document to account for the review
feedback and other issues. Please see
http://apple.github.io/swift-internals/api-design-guidelines/
(presentation view)
and

https://github.com/apple/swift-internals/blob/gh-pages/api-design-guidelines/index.md
(source and commit history)

--
-Dave

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

--
-Dave

7

Dave,

At one point there was discussion of special handling of prepositional
phrases containing “of”, with the “of” being placed before the
parenthesis rather than in the argument label. Was that left out of
the guidelines deliberately or inadvertently (or did I miss it)?

Deliberately. We prepared a diff that made this change
(https://github.com/apple/swift-3-api-guidelines-review/commit/36662d0fb98499811f58f73deeef80b36e2156a8\),
but on review it we found that while it made some things “feel nicer,” it
never added actual clarity, so we could find no justification for
complicating the guidelines to make “of” a special case.

···

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

—CK

On Feb 16, 2016, at 6:31 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

I've updated the API guidelines document to account for the review
feedback and other issues. Please see
http://apple.github.io/swift-internals/api-design-guidelines/
(presentation view)
and
https://github.com/apple/swift-internals/blob/gh-pages/api-design-guidelines/index.md
(source and commit history)

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

8

Thanks, Charles! Could I entice you to submit a pull request against
https://github.com/apple/swift-internals/blob/gh-pages/api-design-guidelines/index.md
with these changes?

(You can do this entirely on GitHub by clicking on the pencil at the top).

···

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

Three places where you might have intended different wording:

"Prefer names of function and other methods that make use sites form grammatical English phrases.”
Should it be:
"Prefer method and function names that make use sites form grammatical English phrases.” ?

“Initializer and factory methods calls should form a phrase that does not include the first argument, e.g.”
Should it be:
“Initializer and factory method calls should form a phrase that does not include the first argument, e.g.” ?

“Label closure parameters and the tuple members where they appear in your API.”
Should it be:
“Label closure parameters and tuple members where they appear in your API.” ?

Also, there appears to be a repeated “the” here:
/// **`byteCount`** equal to the the number of maximally-aligned

—CK

On Feb 16, 2016, at 6:31 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

I've updated the API guidelines document to account for the review
feedback and other issues. Please see
http://apple.github.io/swift-internals/api-design-guidelines/
(presentation view)
and
https://github.com/apple/swift-internals/blob/gh-pages/api-design-guidelines/index.md
(source and commit history)

--
-Dave

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

--
-Dave

9

Nice, I dig the changes.

Some wording wrinkles here and there,

PRs are always welcome:

···

Sent from my moss-covered three-handled family gradunza

On Feb 24, 2016, at 12:23 AM, Radosław Pietruszewski <radexpl@gmail.com> wrote:

but I’m glad feedback from the community was incorporated.

Cheers,
— Radek

On 17 Feb 2016, at 03:31, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

I've updated the API guidelines document to account for the review
feedback and other issues. Please see
http://apple.github.io/swift-internals/api-design-guidelines/
(presentation view)
and
https://github.com/apple/swift-internals/blob/gh-pages/api-design-guidelines/index.md
(source and commit history)

--
-Dave

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

10

I saw that that Markdown file wasn't on master so I didn't think a PR was
appropriate. I just looked, and it appears that gh-pages is the only branch
there.

···

On Wed, Feb 17, 2016 at 1:01 PM, Dave Abrahams via swift-evolution < swift-evolution@swift.org> wrote:

on Tue Feb 16 2016, Trent Nadeau <swift-evolution@swift.org> wrote:

> I like.
>
> Minor grammar fix: Remove the comma in "declared only once, but used
> repeatedly" in the first rule.

Thanks!

FYI, for the future, pull requests work great :-)

> On Tue, Feb 16, 2016 at 9:31 PM, Dave Abrahams via swift-evolution < > > swift-evolution@swift.org> wrote:
>
>>
>> I've updated the API guidelines document to account for the review
>> feedback and other issues. Please see
>> http://apple.github.io/swift-internals/api-design-guidelines/
>> (presentation view)
>> and
>>
>>
https://github.com/apple/swift-internals/blob/gh-pages/api-design-guidelines/index.md
>> (source and commit history)
>>
>> --
>> -Dave
>>
>> _______________________________________________
>> 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

--
Trent Nadeau

11

Thanks, Charles! Could I entice you to submit a pull request against
https://github.com/apple/swift-internals/blob/gh-pages/api-design-guidelines/index.md
with these changes?

Will do.

···

On Feb 18, 2016, at 4:07 PM, Dave Abrahams <dabrahams@apple.com> wrote:

(You can do this entirely on GitHub by clicking on the pencil at the top).

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

Three places where you might have intended different wording:

"Prefer names of function and other methods that make use sites form grammatical English phrases.”
Should it be:
"Prefer method and function names that make use sites form grammatical English phrases.” ?

“Initializer and factory methods calls should form a phrase that does not include the first argument, e.g.”
Should it be:
“Initializer and factory method calls should form a phrase that does not include the first argument, e.g.” ?

“Label closure parameters and the tuple members where they appear in your API.”
Should it be:
“Label closure parameters and tuple members where they appear in your API.” ?

Also, there appears to be a repeated “the” here:
/// **`byteCount`** equal to the the number of maximally-aligned

—CK

On Feb 16, 2016, at 6:31 PM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

I've updated the API guidelines document to account for the review
feedback and other issues. Please see
http://apple.github.io/swift-internals/api-design-guidelines/
(presentation view)
and
https://github.com/apple/swift-internals/blob/gh-pages/api-design-guidelines/index.md
(source and commit history)

--
-Dave

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

--
-Dave

12

I saw that that Markdown file wasn't on master so I didn't think a PR was
appropriate. I just looked, and it appears that gh-pages is the only branch
there.

Nothing wrong with that; you can submit a PR against any branch.

···

on Wed Feb 17 2016, Trent Nadeau <swift-evolution@swift.org> wrote:

On Wed, Feb 17, 2016 at 1:01 PM, Dave Abrahams via swift-evolution < > swift-evolution@swift.org> wrote:

on Tue Feb 16 2016, Trent Nadeau <swift-evolution@swift.org> wrote:

> I like.
>
> Minor grammar fix: Remove the comma in "declared only once, but used
> repeatedly" in the first rule.

Thanks!

FYI, for the future, pull requests work great :-)

> On Tue, Feb 16, 2016 at 9:31 PM, Dave Abrahams via swift-evolution < >> > swift-evolution@swift.org> wrote:
>
>>
>> I've updated the API guidelines document to account for the review
>> feedback and other issues. Please see
>> http://apple.github.io/swift-internals/api-design-guidelines/
>> (presentation view)
>> and
>>
>>
https://github.com/apple/swift-internals/blob/gh-pages/api-design-guidelines/index.md
>> (source and commit history)
>>
>> --
>> -Dave
>>
>> _______________________________________________
>> 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

--
-Dave

13

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.

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.

Jacob

···

On Wed, Feb 17, 2016 at 11:55 AM, Dave Abrahams via swift-evolution < swift-evolution@swift.org> wrote:

on Wed Feb 17 2016, Trent Nadeau <swift-evolution@swift.org> wrote:

> I saw that that Markdown file wasn't on master so I didn't think a PR was
> appropriate. I just looked, and it appears that gh-pages is the only
branch
> there.

Nothing wrong with that; you can submit a PR against any branch.

> On Wed, Feb 17, 2016 at 1:01 PM, Dave Abrahams via swift-evolution < > > swift-evolution@swift.org> wrote:
>
>>
>> on Tue Feb 16 2016, Trent Nadeau <swift-evolution@swift.org> wrote:
>>
>> > I like.
>> >
>> > Minor grammar fix: Remove the comma in "declared only once, but used
>> > repeatedly" in the first rule.
>>
>> Thanks!
>>
>> FYI, for the future, pull requests work great :-)
>>
>> > On Tue, Feb 16, 2016 at 9:31 PM, Dave Abrahams via swift-evolution < > >> > swift-evolution@swift.org> wrote:
>> >
>> >>
>> >> I've updated the API guidelines document to account for the review
>> >> feedback and other issues. Please see
>> >> http://apple.github.io/swift-internals/api-design-guidelines/
>> >> (presentation view)
>> >> and
>> >>
>> >>
>>
https://github.com/apple/swift-internals/blob/gh-pages/api-design-guidelines/index.md
>> >> (source and commit history)
>> >>
>> >> --
>> >> -Dave
>> >>
>> >> _______________________________________________
>> >> 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
>>

--
-Dave

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

14

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?

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.

···

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

Jacob

On Wed, Feb 17, 2016 at 11:55 AM, Dave Abrahams via swift-evolution < > swift-evolution@swift.org> wrote:

on Wed Feb 17 2016, Trent Nadeau <swift-evolution@swift.org> wrote:

> I saw that that Markdown file wasn't on master so I didn't think a PR was
> appropriate. I just looked, and it appears that gh-pages is the only
branch
> there.

Nothing wrong with that; you can submit a PR against any branch.

> On Wed, Feb 17, 2016 at 1:01 PM, Dave Abrahams via swift-evolution < >> > swift-evolution@swift.org> wrote:
>
>>
>> on Tue Feb 16 2016, Trent Nadeau <swift-evolution@swift.org> wrote:
>>
>> > I like.
>> >
>> > Minor grammar fix: Remove the comma in "declared only once, but used
>> > repeatedly" in the first rule.
>>
>> Thanks!
>>
>> FYI, for the future, pull requests work great :-)
>>
>> > On Tue, Feb 16, 2016 at 9:31 PM, Dave Abrahams via swift-evolution < >> >> > swift-evolution@swift.org> wrote:
>> >
>> >>
>> >> I've updated the API guidelines document to account for the review
>> >> feedback and other issues. Please see
>> >> http://apple.github.io/swift-internals/api-design-guidelines/
>> >> (presentation view)
>> >> and
>> >>
>> >>
>>
https://github.com/apple/swift-internals/blob/gh-pages/api-design-guidelines/index.md
>> >> (source and commit history)
>> >>
>> >> --
>> >> -Dave
>> >>
>> >> _______________________________________________
>> >> 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
>>

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

15

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

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

···

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:

16

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

···

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

17

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?

18

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

19

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

20

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