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

Tue Feb 2 18:28:48 CST 2016

> On Feb 2, 2016, at 15:49, Kevin Schlei <kevinschlei at gmail.com> wrote:
> 
> (reply-all reposting, sorry I'm not very list-serve savvy)
> 
> I think it's only unclear because p is not a descriptive name (next and current aren't terribly helpful either), and we don't have any context or type information.
> 
> Put another way: it's up to variable names to clarify what a method does. I'm not in favor of that, and right now it's not broken. (To be clear: I'm all for properly naming variables. I hope everyone else is the same.)
> 
> True, I intentionally chose ambiguous variable names to illustrate a point. However, I have to admit that when unpacking optionals I have caught myself doing this occasionally:
> 
> if let p = proximity {
> 
> } 

To be honest, I don't really agree with the practice of abbreviating names in that way unless it's something so common that it could be considered universally understood (like i in a loop, not that that's a very common pattern in Swift), so I wouldn't find myself in this kind of situation. But even then, unless the body of the if statement is enormous, you can easily refer to the binding to see that p stands for proximity, so context makes all the difference here.

> This is definitely more clear when you completely separate these lines from their context, but code isn't written or read in complete isolation like this, so I think these examples significantly exaggerate the ambiguity of the pattern in the real world.
> 
> In my experience, encountering new code is an exercise in unpacking individual components in order to understand the whole. Making the individual parts convey less makes the whole thing harder to absorb.

I disagree -- when I'm looking at new code, I generally try to get a high-level understanding before diving into specifics, and extra verbosity tends to distract me from that and slow me down. Dense, terse code that leverages its context tends to be much quicker for me to understand since I don't have to filter out the noise words.

But it seems like this is something that's highly personal, and it may be that our disagreement simply comes from the fact that we read and process code differently. That's unfortunate if that's the case, since it would mean that one of us ultimately must accept that we're not working in an environment that's ideal for us individually, but at least we now have the opportunity to express our thoughts so we can make the best decision for the Swift community as a whole.

Jarod

> On Tue, Feb 2, 2016 at 2:48 PM, <swift at lng.la <mailto:swift at lng.la>> wrote:
> 
>> On Feb 2, 2016, at 11:16, Kevin Schlei via swift-evolution <swift-evolution at swift.org <mailto: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:
> 
> I think it's only unclear because p is not a descriptive name (next and current aren't terribly helpful either), and we don't have any context or type information.
> 
>> let next = current.locationByUpdatingProximity(p)
> 
> This is definitely more clear when you completely separate these lines from their context, but code isn't written or read in complete isolation like this, so I think these examples significantly exaggerate the ambiguity of the pattern in the real world.
> 
> Even if you only make the minor change of renaming p to proximity (which is really what it should be), the first example becomes pretty clear:
> 
>> let next = current.updating(proximity)
> 
> 
> Ultimately, I don't think this is a very difficult pattern to learn. Maybe the first handful of times you see it you'll need to read the documentation to know exactly what it's doing, but once you've seen it a few times, it's an instantly recognizable pattern. If you see a gerund method, it returns a new thing by doing the verb to the thing. Is it worth the redundancy and noise to save new developers from possibly needing to look at a method's documentation a few times?
> 
> I see the tradeoff here as a minor, essentially one-time decrease in clarity for new developers, and a small but indefinite increase in clarity for everyone else.
> 
>> 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.
> 
> Not having used this pattern before isn't a valid reason to not start using it, and the API design guidelines already provide a fine pattern for boolean properties, so we don't need gerunds for them.
> 
>> 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 agree that this is kind of unfortunate, but I also don't think that it's a good idea to limit our API design for the sake of autocomplete discovery. Documentation is readily available and is a far better form of discovery since you don't just see things that start with the same prefix that you're using. The tradeoff is that you have to go out of your way to do it, but these are the kinds of good habits we should be teaching students.
> 
>> 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 <mailto: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 <mailto:swift-evolution at swift.org>
>> https://lists.swift.org/mailman/listinfo/swift-evolution <https://lists.swift.org/mailman/listinfo/swift-evolution>
> 
> 

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