[swift-evolution] [Review] SE-0023 API Design Guidelines

[Dave Abrahams]

on Fri Jan 22 2016, Joe Groff <swift-evolution at swift.org> wrote:

>> On Jan 22, 2016, at 1:57 PM, Jeff Kelley via swift-evolution
>> <swift-evolution at swift.org> wrote:
>> 
>>> On Jan 22, 2016, at 4:53 PM, Joe Groff via swift-evolution
>>> <swift-evolution at swift.org
>
>>> <mailto:swift-evolution at swift.org>>
>>> wrote:
>>> 
>>> How do you handle naming non-mutating versions of these operations?
>>> Conjugating other irregular verbs also imposes a barrier on
>>> developers whose first language is not English.
>> 
>> Swift could use “after” as a prefix, or something similar.
>> 
>> array.sort()
>> array.afterSort()
>> 
>> I was tempted to say “afterSorting()” but that has the same problems mentioned above.
>
> That's reminiscent of the way the classic Cocoa naming guidelines
> cleverly avoided these issues by using the 'did-' prefix consistently
> instead of ever conjugating verbs into preterite tense. 'after' is a
> bit awkward, though, as are any other equivalent prefixes i can think
> of that have the same effect on the past participle (havingSplit?
> bySplitting?)

"splitting" works perfectly well on its own, IMO.  If there's an
argument to the method, you'll want some kind of preposition like "At"
or "On" afterwards.

I think the real problem cases for this guideline as written are the
ones where there's no underlying verb, like "union", or where the verb
already has a strong non-mutating connotation, like "exclusiveOr."
Those are the ones that really cry out for a different convention, like
"InPlace."  

In developing the guidelines, we had some internal arguments about
whether it was worth adding complexity to accomodate those cases, or
whether we should simply not mention them and let them get sorted out on
a case-by-case basis when they come up in code review.  We didn't reach
consensus, so this would be a useful area in which to get community
input.

-- 
-Dave