[swift-evolution] API Guidelines Update

[Craig Cruden]

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.  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/b05dffcb/attachment.html>