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

[Dave Abrahams]

on Wed Feb 03 2016, Kevin Schlei <kevinschlei-AT-gmail.com> wrote:

> On Tue, Feb 2, 2016 at 3:21 PM, Dave Abrahams via swift-evolution <
> swift-evolution at swift.org> wrote:
>
>> It trims.  In this case, it trims whitespace and newlines.  I think
>> that's actually pretty clear.
>>
>
> I wouldn't explain what trimming: does to a new student by just saying 'it
> trims', because by that explanation it sounds like it mutates its
> caller.

Uh, fine, for new students: it makes a copy, trims that, and returns it.

> The clarity provided by the verbosity of the old method name will be missed.
>
> I do appreciate your clarification of how my updating: example would not
> meet the new standards, but I find all of the new standards difficult to
> get right. If 'Proximity' is a type, wouldn't that be truncated because it
> doesn't communicate semantics? 

It would be omitted if it were a strong type.  If it was just a
typealias for Float, you'd add it to clarify the role of the argument.

> It feels like half of the methods will have clarifying qualifiers, and
> half won't. I think that will make the language less consistent.

Yes, it is less uniform than code written to the existing conventions.
On balance, it leads to clearer code.  

If this makes you work a little harder to choose good API names, that's
a net plus. In reviewing existing APIs written against the existing
standards, I can't tell you how many times I've found names that are
ambiguous—or worse, strongly imply something unintented—but fit the
usual linguistic patterns. As long as you spell it "noun1ByVerbingNoun2"
or "verbWithNoun" people who are used to reading this kind of
declaration but aren't paying *really close* attention to detail nod
their head and says "yep, sounds about right," and fail to even look at
the resulting code, much less read it the way a new maintainer will.
The familiar patterns lead us into complacency.

> 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.
>>
>
> You've solved the repetition of type detail be removing all type detail.
> That line is clear to you because you already know that .
> whitespaceAndNewlines is an NSCharacterSet, and that string trims
> characters instead of something else, like length. 

Not really.  I do know is that "trim" is a term of art for string
manipulation, and I happen to know what it means.  Even if you put the
type information back in, nothing in the name is going to tell you that
this call removes stuff on the ends of the string but not in the
middle.  That's a much more essential piece of information than the type
of the argument.

> There is nothing written on that line of code that tells me what
> .whitespaceAndNewlines is. It looks like a poorly capitalized enum.

You can't read one line of code by itself anyway just like you can't
generally take a sentence out of context and understand it.

> We don't always read code from within our tools. I can't command-click
> variables on Stackoverflow, WWDC slides, GitHub. I could read 100 lines of
> trimming: and still not know that NSCharacterSet exists.

Fortunately if someone wrote 100 lines of trimming with no other
context, it would be pretty easy to infer that by the end there would be
nothing left ;-)

P.S. FWIW, as a standard library developer, I mostly can't use Xcode for
     development, so command-click is not something I get to rely on.

-- 
-Dave