[swift-evolution] API Guidelines Update

[David Owens II]

> On Feb 24, 2016, at 11:25 AM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 
> on Wed Feb 24 2016, David Owens II <swift-evolution at swift.org> wrote:
> 
>>> On Feb 22, 2016, at 11:02 AM, Jordan Rose via swift-evolution
>>> <swift-evolution at swift.org> wrote:
>>> 
>>> In case it's been lost in all the discussion, the -ing/-ed rule is
>>> essentially the rule Objective-C uses, minus the noun labels for the
>>> return value and types and the word "by". It's definitely very
>>> different grammatically from most other API guidelines, but so are
>>> Objective-C's guidelines.
>>> 
>> 
>> Sure, but I'd actually argue that the noun-labels in ObjC are what
>> actually provide the context of the non-mutating nature of the
>> function. 
> 
> I disagree with that assertion.  The nouns tell you what type is going
> to be returned and what type is being passed, not whether there will be
> mutation to the receiver.

The noun tells you the object that will be worked with.

`stringByTrimmingCharactersInSet(_:)` - return a string by trimming characters in set

`trimCharactersInSet(_:)`, `trim(_:)`, and `trimming(_:)` all read: return myself by trimming characters in set; there is no noun, so it is implied that it's the caller of the function.

The first two guidelines already captures this sentiment as well:

  1. "Those without side-effects should read as noun phrases".
  2. "Those with side-effects should read as imperative verb phrases."

>> I think we are opening ourselves up to the potential of many confusing
>> APIs when an -ed/-ing form of a function name is an appropriate
>> candidate with the opposite meaning that the guidelines set out.
>> 
>> The -ed/-ing suffix choice doesn't seem outright bad, but it does seem
>> to be "death by paper cuts" bad, at least to me. The guidelines are
>> already a bit complicated in this area. Also, like others, I find the
>> -ing suffix to imply a state of work to be done that will be completed
>> later or cover an extended amount of time; mutation has no bearing on
>> the implementation choice here.
>> 
>> Side note: the guidelines are also unintentionally narrow: "Use the
>> “ed/ing” rule to name the nonmutating counterpart of a mutating
>> method."
>> 
>> We should *always* be following this pattern regardless of the
>> existence of a nonmutating counterpart. Otherwise, if you implement
>> just a non-mutating function for sorting without the counterpart, you
>> need to use a noun-phrase, like `sortBy`. Then if you later add a
>> mutating version, you need to rename the `sortBy` to `sorted`. That
>> seems like the wrong outcome of the guidelines.
> 
> I think you're confused: `sortBy(x)`—or more properly, `sort(by:
> x)`—isn't a noun-phrase; it's an imperative verb phrase, so it would be
> an ineligible form for a nonmutating method call.

I think you threw out the baby with the bathwater because of a technicality there. Let's try again.

The stages of an API development process might look like this:

version 1: "Those without side-effects should read as noun phrases"

func contentsOf(filter:) -> Self  // returns a copy

version 2: "Those with side-effects should read as imperative verb phrases"

func contentsOf(filter:) -> Self  // returns a copy
mutating func filter(by:)         // honestly, I'm not sure where the preposition debate has landed...

version 3, bug comes in that the API doesn't meet the guidelines.

func filtered(by:) -> Self  // returns a copy
mutating func filter(by:)

Unless I'm misunderstanding the guidelines, this is the natural progression of the API (minus the `by` preposition, which is irrelevant to this discussion). 

In my opinion, the guidelines should not lead us down breaking API changes as the API evolves. The entire -ed/-ing confuses the entire section, and requires future knowledge of what the future API will look like beforehand. This circles back to my first point about the noun actually serving as more information that the type.

-David
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160224/3ef69fac/attachment.html>