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

[Dave Abrahams]

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

> Sorry for the premature send! Continuing:

Ah, thank you...

> let content = listItemView.text.trimming(.whitespaceAndNewlines)
>
> For a beginning programmer, there is no indication of what .trimming
> does.

It trims.  In this case, it trims whitespace and newlines.  I think
that's actually pretty clear.

> In this case, it returns a new string instance. 

That isn't what it *does*; that's the type it returns.

> Where is that explained? In the documentation. Nowhere near the method
> call.

Exactly.  You get this information from context.  If you take some text
and you trim off the whitespace and newlines, you get some other text.

I don't believe that teaching students that the name of a method is
going to supply all the relevant type information is doing them a
service.  This is *not* what they'll encounter in the real world,
not even if they're programming in Objective-C and using Cocoa.

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

It's 75% unclear because there's no context.  I have no idea what
current or p are.  But I *can* tell (assuming this is following the
guidelines), that the method returns a modified version of current that
is obtained by updating p (whatever that means).

> 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'*

Under the proposed guidelines, that would be:

  let next = current.updatingProximityWith(p)

or

  let next = current.replacingProximityWith(p)

or

  let next = current.settingProximityTo(p)

> When is the last time you saw a gerund (-ing) as a method name? 

FWIW, these are not gerunds, they're present participles.

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

You're presuming that the guidelines as written would endorse that line,
but they don't.  Clarity at the point of use is the prime directive.

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

These things can be handled in other ways, e.g. by improving the tools,
without punishing readability at the use-site by adding needless words.

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

It is.  You just have a different idea about what creates clarity in
source code.  IMO, clarity is provided by communicating semantics, *not*
by repeating non-semantic details such as which specific types are in
use.  By eliminating words that don't communicate semantics, you make
the semantics clearer.  If we didn't believe in this approach, Swift
wouldn't have type inference.

HTH,

-- 
-Dave