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

[Preston Sumner]

Where context fails, tools can go the rest of the way (option-clicking a symbol in Xcode displays a documentation popover). Failing that, referring to external documentation isn’t necessarily a failure of the API. No API can self-document everything. Cocoa methods already can’t be relied on for type documentation.

What are the types of s2, options, and result?
let result = s1.compare(s2, options: [])

Is copy a noun or a verb?
foo.copy()

What type is p?
string.hasPrefix(p)

What is foo?
obj.isDescendantOf(foo)

Preston

> On Feb 3, 2016, at 8:46 AM, Kevin Schlei via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 
> 
> On Tue, Feb 2, 2016 at 3:21 PM, Dave Abrahams via swift-evolution <swift-evolution at swift.org <mailto: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. 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 feels like half of the methods will have clarifying qualifiers, and half won't. I think that will make the language less consistent.
> 
> 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. There is nothing written on that line of code that tells me what .whitespaceAndNewlines is. It looks like a poorly capitalized enum.
> 
> 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.
> 
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

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