[swift-evolution] API Guidelines Update

[Dave Abrahams]

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

> On Wed, Feb 17, 2016 at 5:43 PM, Dave Abrahams <dabrahams at 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 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?
>>
>
> 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...

-- 
-Dave