[swift-evolution] API Guidelines Update

[Charles Kissinger]

> On Feb 19, 2016, at 5:20 PM, Craig Cruden <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)

—CK

> It is not that I don’t accept and embrace
> change — if that were the case I would not be constantly learning.  
> 
> “ing” (the worst of the two) to me infers that something is in progress… i.e. “process”.isRunning or “process”.running.  
> 
> “ed” (least worst) to me infers that you are querying the state of something “process”.completed.  
> 
> Both mutable and immutable execute and complete and results are either returned or applied.
> 
> I have generally (maybe always) kept things that “mutate” separate from things that don’t (unless I am working in a 
> system where immutable vs mutable never entered the mind of the developer).  It feels more focused.  In most cases
> it is fairly easy to do, and cleaner.  I don’t know if there is some performance reason why the mixing of the 
> two (across the whole API) is more advantageous.  But even in that case it will constantly be nagging me, and 
> giving me the feeling that something went horribly wrong and it is something that needs to be looked at to 
> see if it needs to be refactored and simplified.  
> 
> So for me it is not just that it is grammatically awkward, it will constantly be giving me a feeling that something went
> horribly wrong and that it needs to be looked at again to see if it could have been done in a more simplified
> and focused way.
> 
> 
> 
> 
>> 
>> As I think you’ve said previously, it’s probably just a case where people (including me) need to get used to the idiom. There is a huge leap from:
>> 
>> a.stringByTrimmingCharactersInSet(b)
>> to:
>> a.trimming(b)
>> 
>> A couple of cognitive crutches that people have depended on are gone. 
>> 
>> There are things that make “-ing” function names more of an adjustment for some people, I think:
>> 
>> - It’s an idiom (if that’s the right word) for function naming that a lot of people haven’t been exposed to before.
>> 
>> - The expression at the call-site is grammatical, but perhaps not common usage, so people might still have to stop and think about what the function is doing until they get used to it.
>> 
>> - Though not a problem unique to “-ing”s, the function's primary purpose is to return something, but the function name by itself doesn’t reflect that (though the full expression at the call site does).
>> 
>> None of these are necessarily flaws, just things that people react to. So it might be reasonable to conclude there isn’t actually a problem. ;-)
>> 
>>> ? Are they hard to read?
>> 
>> In the limited sense of being unfamiliar usage for some people. It doesn’t seem grammatically awkward to me.
>> 
>>> Is it hard to arrive at these names, somehow?
>> 
>> Not IMO.
>> 
>>> Are the guidelines simply not clear enough about the procedure for
>>> producing names mutating/non-mutating pairs?
>> 
>> I think the people who have raised concerns are reacting to the aesthetics of particular examples and not to the difficultly of using the naming conventions.
>> 
>>> Is it too easy to confuse that part of the guidelines with the general direction regarding methods with/without side-effects?
>> 
>> Without the examples, I think it might be confusing because you’re sorting through grammar rules. The examples provide the clarity.
> 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160220/3c915472/attachment.html>