[swift-evolution] API Guidelines Update
jtbandes at gmail.com
Wed Feb 17 20:08:52 CST 2016
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>
> >> > 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*"?
> >> > 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
> >> > I think that "var expandingTildeInPath" is probably the best choice
> >> > this API, but I can't figure out how to reconcile it with the
> >> 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
> > other types, properties, variables, and constants should read as nouns
> > 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...", so there might be some cases where it's
easy to confuse Bool properties with non-Bools.
-------------- next part --------------
An HTML attachment was scrubbed...
More information about the swift-evolution