[swift-evolution] API Guidelines Update

[Dave Abrahams]

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?

> 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.

>
> 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
>>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-- 
-Dave