[swift-evolution] API Guidelines Update

[Jacob Bandes-Storch]

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.

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.

Jacob

On Wed, Feb 17, 2016 at 11:55 AM, Dave Abrahams via swift-evolution <
swift-evolution at swift.org> wrote:

>
> on Wed Feb 17 2016, Trent Nadeau <swift-evolution at swift.org> wrote:
>
> > I saw that that Markdown file wasn't on master so I didn't think a PR was
> > appropriate. I just looked, and it appears that gh-pages is the only
> branch
> > there.
>
> Nothing wrong with that; you can submit a PR against any branch.
>
> > On Wed, Feb 17, 2016 at 1:01 PM, Dave Abrahams via swift-evolution <
> > swift-evolution at swift.org> wrote:
> >
> >>
> >> on Tue Feb 16 2016, Trent Nadeau <swift-evolution at swift.org> wrote:
> >>
> >> > I like.
> >> >
> >> > Minor grammar fix: Remove the comma in "declared only once, but used
> >> > repeatedly" in the first rule.
> >>
> >> Thanks!
> >>
> >> FYI, for the future, pull requests work great :-)
> >>
> >> > On Tue, Feb 16, 2016 at 9:31 PM, Dave Abrahams via swift-evolution <
> >> > swift-evolution at swift.org> wrote:
> >> >
> >> >>
> >> >> I've updated the API guidelines document to account for the review
> >> >> feedback and other issues.  Please see
> >> >> http://apple.github.io/swift-internals/api-design-guidelines/
> >> >> (presentation view)
> >> >> and
> >> >>
> >> >>
> >>
> https://github.com/apple/swift-internals/blob/gh-pages/api-design-guidelines/index.md
> >> >> (source and commit history)
> >> >>
> >> >> --
> >> >> -Dave
> >> >>
> >> >> _______________________________________________
> >> >> swift-evolution mailing list
> >> >> swift-evolution at swift.org
> >> >> https://lists.swift.org/mailman/listinfo/swift-evolution
> >> >>
> >>
> >> --
> >> -Dave
> >>
> >> _______________________________________________
> >> swift-evolution mailing list
> >> swift-evolution at swift.org
> >> https://lists.swift.org/mailman/listinfo/swift-evolution
> >>
>
> --
> -Dave
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160217/3af36d41/attachment.html>