[swift-evolution] API Guidelines Update

[Jacob Bandes-Storch]

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...", so there might be some cases where it's
easy to confuse Bool properties with non-Bools.
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160217/b2bcef51/attachment.html>