[swift-evolution] API Guidelines Update

[Dave Abrahams]

on Fri Feb 19 2016, Craig Cruden <swift-evolution at swift.org> 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” 

Wrong order; “ed”/“ing” please!  ;-)

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

Ah; I understand.  The guidelines specify that for this purpose the
above should read like an assertion about the receiver,
e.g. “process.isRunning,” and heretofore Cocoa has always used
“process.running.”  So I can see why it might be hard to re-train your
instincts on this.

> “ed” (least worst) to me infers that you are querying the state of
> something “process”.completed.

Same applies here.

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

Let's just consider sets, for example.  If an in-place
intersection suits what you're trying to do, then

  x.intersectWith(y) // or however you spell it; mutating

can avoid doing any new allocations and most of the data copying that
would otherwise be result from

  x = x.intersection(y) // or however you spell it; non-mutating

It's certainly possible to argue that sets should only have mutating
operations, but that seems like a really harsh break with tradition, and
would make combining sets that are immutable due to “let” bindings quite
awkward.

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

Hmm, I understand that... But maybe you should watch
https://developer.apple.com/videos/play/wwdc2015-414/ (again).  We want
programmers to be really comfortable with mutation.  The premise behind
our emphasis on value types is that the real underlying problem that
drives people to create immutable data structures is usually implicit
sharing, rather than mutation.


>> 
>> 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.
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-- 
-Dave