<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"></head><body dir="auto"><div></div><br><blockquote type="cite"><div><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">On Feb 7, 2016, at 10:50, Dave Abrahams via swift-evolution <<a href="mailto:swift-evolution@swift.org">swift-evolution@swift.org</a>> wrote:<br><br></span></font></div><div><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><<schnipp>></span></font></div><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br>Gah! Well if you'd like to post those messages here, you certainly have<br>my permission. It might be good to have them as part of the public<br>record.</span></font></blockquote><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font><div><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">Here was my original email:</span></font></div><div><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></div><div><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">I certainly can live with these guidelines (and although I have a slight preference for something like move(from: a, to: b), it is only a _slight_ preference). However, I do have a suggested tweak to A. that I believe maintains clarity of guidance and covers this case. (See below inline)<br><br></span></font><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">On Feb 5, 2016, at 16:32, Dave Abrahams via swift-evolution <<a dir="ltr" href="mailto:swift-evolution@swift.org" x-apple-data-detectors="true" x-apple-data-detectors-type="link" x-apple-data-detectors-result="3">swift-evolution@swift.org</a>> wrote:<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">Given all the awesome feedback I've gotten on this thread, I went back<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">to the drawing board and came up with something new; I think this one<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">works. The previously-stated goals still apply:<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">* describe when and where to use argument labels<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">* require labels in many of the cases people have asked for them<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">* are understandable by humans (this means relatively simple)<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">* preserve important semantics communicated by existing APIs.<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">Please keep in mind that it is a non-goal to capture considerations we<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">think have a bearing on good names (such as relatedness of parameters):<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">it's to create simple guidelines that have the right effect in nearly<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">all cases.<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">A. When arguments can't be usefully distinguished from one another, none<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> should have argument labels, e.g. min(x,y), zip(x,y,z). </span></font></blockquote><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br>When arguments' _importance_ can't be usefully distinguished from one another, none should have argument labels or _all should have argument labels_, e.g. min(x,y), zip(x,y,z), move(from: a, to: b), moveTo(x: a, y: b)<br><br></span></font><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">B. Otherwise,<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">1. At the call site, a first parameter that has no argument label must<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> form part of a grammatical phrase that starts with the basename, less<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> any trailing nouns. <br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> print(x)<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> a.contains(b)<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> a.mergeWith(b)<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> a.addGestureRecognizer(x)<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> ^~~~~~~~~~~~~~~~~ trailing noun</span></font></blockquote><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br>One other potential concern. I understand (and wholeheartedly agree) that GestureRecognizer should be pet of the base name here, but I'm not sure I see where the guidance explains it to me.<br><br></span></font><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> This phrase must have the correct semantic implications, so, e.g.<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> a.dismiss(b) // no, unless a is really dismissing b<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> a.dismissAnimated(b) // no, not grammatical<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> a.dismiss(animated: b) // yes, using a label<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">2. If the first argument is part of a prepositional phrase, put the<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> parenthesis immediately after the preposition. <br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> a.encodeWith(b)<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> a.moveFrom(b, to: c)<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> Thus, if words are required for any reason between the preposition<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> and the first argument, they go into the first argument label.<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> a.tracksWith(mediaType: b, composer: c)<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> a.moveTo(x: 22, y: 99)<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">Notes: <br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">a. I would recommend prepositions other than "with" in nearly all<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> cases, but that's not the point of these rules.<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">b. I can understand the aesthetic appeal of<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> a.move(from: b, to: c)<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> but I believe it is not a clear enough improvement to justify<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> additional complexity in the guidelines.<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">Questions:<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">1. I'm not expecting these guidelines to make everybody optimally happy,<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> all the time, but they shouldn't be harmful. Are there any cases for<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> which they produce results you couldn't live with?<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">2. Are there any cases where you'd be confused about how to apply these<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> guidelines?<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">Thanks in advance for all your valuable input!<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">P.S. Doug is presently working on generating new importer results, based<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> on these guidelines, for your perusal. They should be ready soon.<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">-- <br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">-Dave<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">_______________________________________________<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);">swift-evolution mailing list<br></span></font></blockquote><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"><a dir="ltr" href="mailto:swift-evolution@swift.org" x-apple-data-detectors="true" x-apple-data-detectors-type="link" x-apple-data-detectors-result="4">swift-evolution@swift.org</a><br></span></font></blockquote><blockquote type="cite"><a dir="ltr" href="https://lists.swift.org/mailman/listinfo/swift-evolution" x-apple-data-detectors="true" x-apple-data-detectors-type="link" x-apple-data-detectors-result="5" style="background-color: rgba(255, 255, 255, 0);"><font color="#000000">https://lists.swift.org/mailman/listinfo/swift-evolution</font></a></blockquote></div></blockquote></body></html>