<html><head><meta http-equiv="Content-Type" content="text/html charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><br class=""><div><blockquote type="cite" class=""><div class="">On Feb 22, 2016, at 11:02 AM, Jordan Rose via swift-evolution <<a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div class="" style="font-family: Helvetica; font-size: 12px; font-style: normal; font-variant: normal; font-weight: normal; letter-spacing: normal; orphans: auto; text-align: start; text-indent: 0px; text-transform: none; white-space: normal; widows: auto; word-spacing: 0px; -webkit-text-stroke-width: 0px;">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.</div><br class="Apple-interchange-newline"></div></blockquote></div><br class=""><div class="">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.</div><div class=""><br class=""></div><blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;" class=""><div class=""><font face="Menlo" class="">stringByTrimmingCharactersInSet(_:)</font></div><div class=""><br class=""></div></blockquote>We are taking information about the returned data out of the function name and assuming that the return type makes up for it.<div class=""><br class=""></div><blockquote style="margin: 0 0 0 40px; border: none; padding: 0px;" class=""><div class=""><div class=""><font face="Menlo" class="">trimming(_:)</font></div></div></blockquote><div class=""><br class=""></div><div class="">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.</div><div class=""><br class=""></div><div class="">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.</div><div class=""><br class=""></div><div class="">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.</div><div class=""><br class=""></div><div class="">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.</div><div class=""><br class=""></div><div class="">Side note: the guidelines are also unintentionally narrow: "Use the “ed/ing” rule to name the nonmutating counterpart of a mutating method."</div><div class=""><br class=""></div><div class="">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. </div><div class=""><br class=""></div><div class="">-David</div></body></html>