[swift-evolution] API Guidelines Update

[Jordan Rose]

> On Feb 24, 2016, at 11:25, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 
> on Wed Feb 24 2016, David Owens II <swift-evolution at swift.org <mailto: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.

For the Cocoa value types, I agree with DavidO that a return-type noun reliably distinguishes mutation from non-mutation, and is a better-than-50% indicator for methods on other types as well. This is part of the established Cocoa convention and is (sort of) called out <https://developer.apple.com/library/mac/documentation/Cocoa/Conceptual/CodingGuidelines/Articles/NamingMethods.html#//apple_ref/doc/uid/20001282-1001751-BCIJHEDH> in the existing (sparse) naming guidelines.

However, I don't think that's that much less subtle than the -ing ending. It's a different cue but not one that's really any more or less noticeable. (Evidence: DaveA did not know it or infer it despite driving this effort, i.e. getting plenty of exposure to many different APIs.)

(The participle ending for nullary methods or properties may be a little more subtle, especially for non-English speakers..)

>> A counter example for -ing usage: if we have a streaming-type and `trimming` is actually the process for continually removing those characters from the stream. The likely implementation of this is going to be a mutating function that fires events, or maybe it's a promise-like API that wraps the event handling differently. The corollary is that `trim` would actually be the one that produces no side-effects as it would be able to give a snapshot of the current state of a trimmed stream.

I can't actually picture this API. 'trimming' and 'trim' don't seem to follow the naming conventions for the operations you've described. Can you write it out?

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

This I definitely agree with. If you have a non-mutating member that returns the same type as the receiver, it should be named as if there could be an in-place version added later.

Jordan

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