<html><head><meta http-equiv="Content-Type" content="text/html charset=utf-8"></head><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class="">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.</div><div class=""><br class=""></div><div class="">What are the types of s2, options, and result?</div><div class="">let result = s1.compare(s2, options: [])</div><div class=""><br class=""></div><div class="">Is copy a noun or a verb?</div><div class="">foo.copy()</div><div class=""><br class=""></div><div class="">What type is p?</div><div class="">string.hasPrefix(p)</div><div class=""><br class=""></div><div class="">What is foo?</div><div class="">obj.isDescendantOf(foo)</div><div class=""><br class=""></div><div class="">Preston</div><div class=""><br class=""></div><div><blockquote type="cite" class=""><div class="">On Feb 3, 2016, at 8:46 AM, Kevin Schlei via swift-evolution <<a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a>> wrote:</div><br class="Apple-interchange-newline"><div class=""><div dir="ltr" class=""><br class=""><div class="gmail_extra"><br class=""><div class="gmail_quote">On Tue, Feb 2, 2016 at 3:21 PM, Dave Abrahams via swift-evolution <span dir="ltr" class=""><<a href="mailto:swift-evolution@swift.org" target="_blank" class="">swift-evolution@swift.org</a>></span> wrote:<br class=""><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">It trims. In this case, it trims whitespace and newlines. I think<br class="">
that's actually pretty clear.<br class=""></blockquote><div class=""><br class=""></div><div class="">I wouldn't explain what <font face="monospace, monospace" class="">trimming:</font> 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.</div><div class=""><br class=""></div><div class="">I do appreciate your clarification of how my <span style="font-family:monospace,monospace" class="">updating: </span>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.</div><div class=""><br class=""></div><blockquote class="gmail_quote" style="margin:0px 0px 0px 0.8ex;border-left-width:1px;border-left-color:rgb(204,204,204);border-left-style:solid;padding-left:1ex">It is. You just have a different idea about what creates clarity in<br class="">
source code. IMO, clarity is provided by communicating semantics, *not*<br class="">
by repeating non-semantic details such as which specific types are in<br class="">
use. By eliminating words that don't communicate semantics, you make<br class="">
the semantics clearer. If we didn't believe in this approach, Swift<br class="">
wouldn't have type inference.<br class=""></blockquote><div class=""><br class=""></div><div class="">You've solved the repetition of type detail be removing all type detail. That line is clear to you because you already know that .<span style="font-size:13px;color:rgb(80,0,80)" class="">whitespaceAndNewlines </span>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 .<span style="font-size:13px;color:rgb(80,0,80)" class="">whitespaceAndNewlines </span>is. It looks like a poorly capitalized enum.</div><div class=""><br class=""></div><div class="">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 <font face="monospace, monospace" class="">trimming:</font> and still not know that NSCharacterSet exists.</div><div class=""><br class=""></div></div></div></div>
_______________________________________________<br class="">swift-evolution mailing list<br class=""><a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a><br class="">https://lists.swift.org/mailman/listinfo/swift-evolution<br class=""></div></blockquote></div><br class=""></body></html>