[swift-evolution] API Guidelines Update

[Dave Abrahams]

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 at swift.org> wrote:
>
>>
>> on Wed Feb 17 2016, Jacob Bandes-Storch <swift-evolution at 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?

-- 
-Dave