[swift-evolution] API Guidelines Update

Jordan Rose jordan_rose at apple.com
Mon Feb 22 13:02:02 CST 2016

> On Feb 20, 2016, at 13:26, Charles Kissinger via swift-evolution <swift-evolution at swift.org> wrote:
>> On Feb 19, 2016, at 5:20 PM, Craig Cruden <ccruden at novafore.com <mailto:ccruden at novafore.com>> wrote:
>> Neither really feel right - I am not against long names, but sometimes people have long names because they are unfocused and the API to a class/type has too many unfocused methods on it.  Then it gets applied to other classes/types with less methods since it is more consistent with the naming of the class/types that they have already completed.  
>> Whereas “ing”/“ed” is against all the naming conventions (closer to opposite of what was acceptable) of any development environment I have worked in the last 30 years.
> Hi Craig,
> I just haven’t been able to come up with a convention that meets Dave’s requirements and is consistently better. The best “-ing” alternative to my eye is “with-":
> s.expandTilde()                       // mutating
> let t = s.withExpandedTilde()   // non-mutating
> x.append(y)
> let z = x.withAppended(y)         // Meh
> a.trim(.whitespaceAndNewlines)
> let b = a.withTrimmed(.whitespaceAndNewlines)

I'll second that. "a.withTrimmed(.whitespaceAndNewlines)" makes no sense to me, i.e. the name "withTrimmed" is hurting comprehension. I tried to figure out why this is and eventually decided my brain was grouping it as "a with [trimmed whitespace]", as if "trimmed whitespace" were a thing. "havingTrimmed" would have been okay (a participle form), but feels clunky.

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.


-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160222/69be0247/attachment.html>

More information about the swift-evolution mailing list