[swift-evolution] Issues with 0005-Better Translation of Objective-C APIs Into Swift

[Dave Abrahams]

on Tue Feb 02 2016, Aaron Crespo <swift-evolution at swift.org> wrote:

> I think Kevin and I come from the same place and largely agree. I feel like
> this is trading in of accessibility and discoverability for the sake of
> terseness. This might be aesthetically pleasing but gives up many positive
> side effects the more descriptive names provide.

This is not about aesthetics; it's about clarifying code by omitting
details that don't carry their weight in terms of communicative power.

> Consider the time before you knew you could or how to "check the
> documentation". Or the time spent scanning unfamiliar or long
> forgotten code.

I am considering that.  Code like this is hard for me to read because
there is a great deal of information that is either redundant or
irrelevant, and I have to filter it out.

  let cleansedString = listItemView.stringValue.stringByTrimmingCharactersInSet(
     NSCharacterSet.whitespaceAndNewlineCharacterSet())

The above is not an improvement over

  let cleansed = listItemView.stringValue.trimming(.whitespaceAndNewlines)

in understandability, especially when you put it in context in a large
program.  Programmers have a great deal of complexity to manage, and
giving them twice the number of words to process in order to understand
a piece of code makes their job a lot harder.

We don't write English that way, for good reason: it results in
impenetrable text.  You might be able to pick apart the details of a
sentence with great precision, but you'll never be able to grasp the
meaning of a paragraph.  The same applies to programs.

> These concerns might be eased if consideration was also being given to the
> first parameter rule. 

If you mean the default for first parameters, some of us are thinking
about that; just not in this thread please.  But regardless, I don't see
how changing the default would address any of your concerns about
comprehensibility of code that follows the guidelines.

> And the (now) odd difference between initializers and function
> parameter names. Apply the same rules as any parameter name.
>
> Stealing Kevins example:
>
> let next = current.updating(proximity: p)
>
> Not great but better.

>
> On Tue, Feb 2, 2016 at 2:16 PM, Kevin Schlei via swift-evolution <
> swift-evolution at swift.org> wrote:
>
>> Sorry for the premature send! Continuing:
>>
>> let content = listItemView.text.trimming(.whitespaceAndNewlines)
>>
>> For a beginning programmer, there is no indication of what .trimming does.
>> In this case, it returns a new string instance. Where is that explained? In
>> the documentation. Nowhere near the method call.
>>
>> So are we reduced now to looking up documentation just to read code? What
>> does this line do:
>>
>> let next = current.updating(p)
>>
>> It's 100% unclear because you're relying on parameter names to contain all
>> the hints. But this line:
>>
>> let next = current.locationByUpdatingProximity(p)
>>
>> Lets you know that:
>>
>> 1. we're returning a *'location'*
>> 2. '*by* *updating' *current with a new *'proximity'*
>>
>> When is the last time you saw a gerund (-ing) as a method name? I wouldn't
>> let my students write that. Gerunds make good boolean properties. How would
>> you even read the first line above out loud? Probably by filling in the
>> words in the second line, magically.
>>
>> My second major issue is that autocomplete grouping is totally lost when
>> dropping the type returned at the beginning of the call. How many of us
>> learned a *ton* when we just autocompleted .stringBy? Look at all the
>> things you can do! But by removing the 'useless word' (really don't like
>> that flag name) we have no grouping of constructor methods.
>>
>> I see a lot of discussion on how to deal with 'with' and 'by' and other
>> words, but I want to strongly suggest that the current naming practices
>> provide context and clarity. It makes code readable and accessible. Don't
>> forget about when you didn't know how to code! These method names are
>> teaching tools!
>>
>> Finally, I just want to ask: why? What is the great benefit? Shouldn't
>> clarity be prioritized over brevity (where have I seen that...)
>>
>> I can't put it better than another forums poster:
>>
>> Does the Swift team seriously believe that systematically parsing and
>>> extensively munging patterns in not-quite-natural-language is tractable to
>>> support all the corner cases for? And that, even if it were, that it could
>>> avoid confusion in less-than-perfect codebases? The idea that this will
>>> somehow benefit a language, particularly one in which clear and obvious
>>> bridging is so vital is *insane*. The best it can do is a reasonable
>>> job, with some amount of either unfixable brokenness forced upon developers
>>> in perpetuity, or constant churn stemming from perpetual fixing of
>>> brokenness. Swift's translation is currently simple to reason about, and
>>> the language as a whole has got a really great thing going on. I'm really
>>> happy with where it is at this moment. Why ruin it by boneheadedly
>>> detonating the utility of two years of progress in literature and the
>>> library of online information about Swift? Seriously, why?
>>>
>>
>>
>>
>> On Tue, Feb 2, 2016 at 1:04 PM, Kevin Schlei
>> <kevinschlei at gmail.com>
>> wrote:
>>
>>> I am strongly against the proposed changes to the translation of
>>> Objective-C APIs. I think the changes promote terseness for terseness sake,
>>> lose vital context in method names, and are a huge loss pedagogically.
>>>
>>> If you teach programming, you'll know why this line will be a nightmare:
>>>
>>> let content = listItemView.text.trimming(.whitespaceAndNewlines)
>>>
>>>
>>
>> _______________________________________________
>> swift-evolution mailing list
>> swift-evolution at swift.org
>> https://lists.swift.org/mailman/listinfo/swift-evolution
>>
>>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-- 
-Dave