[swift-evolution] API Guidelines Update

[Jacob Bandes-Storch]

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.

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)*."
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160217/55e93ec5/attachment.html>