[swift-evolution] API Guidelines Update

[Jordan Rose]

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

Jordan


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