[swift-evolution] API Guidelines Update

[David Owens II]

> 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. The -ed/-ing suffixes are a by-product of the preceding noun-phrase and/or trailing preposition.

stringByTrimmingCharactersInSet(_:)

We are taking information about the returned data out of the function name and assuming that the return type makes up for it.

trimming(_:)

For a string-type, that may be ok, but I'd argue that `trimming` is significantly more ambiguous that the ObjC version. There is no reasonable assumption that `stringByTrimmingCharactersInSet` would ever mutate the caller. However, `trimming` carries no such implication _unless_ you are well versed in the API guidelines, and even then, I'd still argue that your confidence level between the two versions is not equal.

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

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