<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=""><br class=""><div><blockquote type="cite" class=""><div class="">On Jan 24, 2016, at 2:23 PM, Paul Cantrell 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 style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class="">Some of the particulars of the guidelines haven’t worked well for me in practice — and I see from this thread that others have hit some of the same problems.</div></div></div></blockquote>…<br class=""><blockquote type="cite" class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class="">In short, in a real-world project, pre-guidelines code agreed with the guidelines 89% of the time, but where it disagreed, the guidelines achieved only a 25% acceptance rate with the curmudgeonly developers.</div><div class=""><br class=""></div><div class="">You can follow that discussion here:</div><div class=""><br class=""></div><div class=""><span class="Apple-tab-span" style="white-space:pre"> </span><a href="https://gist.github.com/pcantrell/22a6564ca7d22789315b" class="">https://gist.github.com/pcantrell/22a6564ca7d22789315b</a></div><div class=""><span class="Apple-tab-span" style="white-space: pre;"> </span><a href="https://github.com/bustoutsolutions/siesta/issues/15" class="">https://github.com/bustoutsolutions/siesta/issues/15</a></div></div></blockquote><blockquote type="cite" class="">…<br class=""></blockquote><blockquote type="cite" class=""><div style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><div class="">I’ll share in a separate message some notes on the other places where we rejected the guidelines on questions other than the first arg label.</div></div></blockquote><br class=""></div><div>Here is that separate message as promised, with real-world examples of where the guidelines didn’t seem right for Siesta for reasons other than first arg naming.</div><div><br class=""></div><div>Interestingly, all of them are part-of-speech questions. I’m intentionally writing up these notes before perusing Erica’s grammar writeup, so I can capture the raw reactions before letting them be colored by that document. Erica, I’ll get to your doc soon!</div><div><br class=""></div><div><b class="">_____________</b></div><div><br class=""></div><div>Siesta uses the widespread fluent style of attaching callbacks to a request:</div><div><br class=""></div><div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo; color: rgb(88, 126, 168);" class=""> resource<span style="font-variant-ligatures: no-common-ligatures; color: #000000" class="">.</span>load<span style="font-variant-ligatures: no-common-ligatures; color: #000000" class="">()</span></div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;" class=""> .onCompletion { <span style="font-variant-ligatures: no-common-ligatures; color: #323e7d" class="">_</span> <span style="font-variant-ligatures: no-common-ligatures; color: #323e7d" class="">in</span> stopSpinnyThing() }</div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;" class=""> <span style="font-size: 10.5px;" class="">.onSuccess { </span><span style="font-size: 10.5px; color: rgb(50, 62, 125);" class="">_</span><span style="font-size: 10.5px;" class=""> </span><span style="font-size: 10.5px; color: rgb(50, 62, 125);" class="">in</span><span style="font-size: 10.5px;" class=""> showHappyFace() }</span></div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;" class=""> .onFailure { <span style="font-variant-ligatures: no-common-ligatures; color: #323e7d" class="">_</span> <span style="font-variant-ligatures: no-common-ligatures; color: #323e7d" class="">in</span> showSadFace() }</div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;" class=""> <span style="font-size: 10.5px;" class="">.onNewData { </span><span style="font-size: 10.5px; color: rgb(50, 62, 125);" class="">_</span><span style="font-size: 10.5px;" class=""> </span><span style="font-size: 10.5px; color: rgb(50, 62, 125);" class="">in</span><span style="font-size: 10.5px;" class=""> soundTrumpets() }</span></div></div><div><br class=""></div><div>These methods mutate the receiving request (by adding a callback), and the guidelines thus say that they should be named as imperative verbs. The results of that don’t seem like an improvement:</div><div><br class=""></div><div><div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo; color: rgb(88, 126, 168);" class=""> resource<span style="color: rgb(0, 0, 0);" class="">.</span>load<span style="color: rgb(0, 0, 0);" class="">()</span></div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;" class=""> .addCompletionCallback { <span style="color: rgb(50, 62, 125);" class="">_</span> <span style="color: rgb(50, 62, 125);" class="">in</span> stopSpinnyThing() }</div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;" class=""> <span style="font-size: 10.5px;" class="">.addSuccessCallback { </span><span style="font-size: 10.5px; color: rgb(50, 62, 125);" class="">_</span><span style="font-size: 10.5px;" class=""> </span><span style="font-size: 10.5px; color: rgb(50, 62, 125);" class="">in</span><span style="font-size: 10.5px;" class=""> showHappyFace() }</span></div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;" class=""> .addFailureCallback { <span style="color: rgb(50, 62, 125);" class="">_</span> <span style="color: rgb(50, 62, 125);" class="">in</span> showSadFace() }</div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;" class=""> <span style="font-size: 10.5px;" class="">.addNewDataCallback { </span><span style="font-size: 10.5px; color: rgb(50, 62, 125);" class="">_</span><span style="font-size: 10.5px;" class=""> </span><span style="font-size: 10.5px; color: rgb(50, 62, 125);" class="">in</span><span style="font-size: 10.5px;" class=""> soundTrumpets() }</span></div></div></div><div><br class=""></div><div>In a related case, it’s possible to attach a callback to be run before any request within a given context:</div><div><br class=""></div><div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo; color: rgb(88, 126, 168);" class=""><span style="font-variant-ligatures: no-common-ligatures; color: #000000" class=""> $0.</span>config<span style="font-variant-ligatures: no-common-ligatures; color: #000000" class="">.</span>beforeStartingRequest<span style="font-variant-ligatures: no-common-ligatures; color: #000000" class=""> {</span></div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;" class=""> _ <span style="font-variant-ligatures: no-common-ligatures; color: #323e7d" class="">in </span><span style="color: rgb(88, 126, 168); font-size: 10.5px;" class="">performDrumroll()</span></div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;" class=""> }</div><div class=""><br class=""></div></div><div>It’s not even clear to me what the imperative verb here should be. Maybe “callBeforeStartingRequest”? The guideline-conforming options are all awkward; the guideline-breaking form above is clear.</div><div><br class=""></div><div>I’d suggest a rule along these lines (but with less convoluted phrasing, if anyone can figure that out):</div><div><b class=""><br class=""></b></div><div><b class="">“When a method’s last argument is a closure, the method’s name and other arguments may read as a clause which modifies the closure as if it were a sentence with an imperative verb.”</b></div><div><br class=""></div><div>Um, yeah, mouthful. Examples may help:</div><div><br class=""></div><div><span class="Apple-tab-span" style="white-space: pre;"> </span>Before starting a request, ← method</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>perform a drumroll. ← closure</div><div><br class=""></div><div><div><span class="Apple-tab-span" style="white-space: pre;"> </span>On completion, ← method</div><div><span class="Apple-tab-span" style="white-space:pre"> </span>stop the spinny thing. ← closure</div><div class=""><br class=""></div></div><div>____</div><div><br class=""></div><div>The ResourceObserver protocol, which clients will implement frequently, consists of “response to event” methods that may or may not mutate the receiver, but probably have side effects. These are methods clients will implement, but probably not call. An example:</div><div><div><br class=""></div><div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;" class=""> <span style="color: rgb(50, 62, 125);" class="">func</span> resourceChanged(resource: <span style="color: rgb(88, 126, 168);" class="">Resource</span>, event: <span style="color: rgb(88, 126, 168);" class="">ResourceEvent</span>) {</div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo; color: rgb(88, 126, 168);" class=""><span style="color: rgb(0, 0, 0);" class=""> </span>tableView<span style="color: rgb(0, 0, 0);" class="">.</span>reloadData<span style="color: rgb(0, 0, 0);" class="">()</span></div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;" class=""> }</div><div class=""><br class=""></div></div><div>The name “resourceChanged” feels right to me. The old-school Cocoa name would be resourceDidChange, which also feels OK. Options that are strictly nouns or verbs — resourceChange, respondToResourceChange — all feel awkward by comparison.</div><div><br class=""></div><div>I think this has something to do with the “responding to event” nature of the method, crossed with the fact that it’s named in a protocol. We can’t know what it does, so we it doesn’t make sense to describe it as a verb. We only know <i class="">why</i> it’s called, what situation it’s responding to.</div></div><div>____</div><div><br class=""></div><div>On the other side of the verb/noun coin, the ResponseTransformer protocol consists of a single method…</div><div><div><br class=""></div><div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;" class=""><div style="margin: 0px; font-size: 10.5px; line-height: normal;" class=""><div style="margin: 0px; font-size: 10.5px; line-height: normal;" class=""> <span style="font-variant-ligatures: no-common-ligatures; color: #323e7d" class="">public</span> <span style="font-variant-ligatures: no-common-ligatures; color: #323e7d" class="">protocol</span> ResponseTransformer {</div><div style="margin: 0px; font-size: 10.5px; line-height: normal; color: rgb(50, 62, 125);" class=""><span style="font-variant-ligatures: no-common-ligatures; color: #000000" class=""> </span>@warn_unused_result</div><div style="margin: 0px; font-size: 10.5px; line-height: normal;" class=""> <span style="font-variant-ligatures: no-common-ligatures; color: #323e7d" class="">func</span> process(response: <span style="font-variant-ligatures: no-common-ligatures; color: #587ea8" class="">Response</span>) -> <span style="font-variant-ligatures: no-common-ligatures; color: #587ea8" class="">Response</span></div><div style="margin: 0px; font-size: 10.5px; line-height: normal;" class=""> }</div><div class=""><br class=""></div><div class=""><div style="font-family: 'Helvetica Neue'; font-size: 13px;">…which is purely functional — should mutate neither the receiver nor the argument — yet just really, really seems wrong to me if it’s not named “process.” Why? I don’t have a rule. My gut just tells me that method should be a verb.</div><div style="font-family: 'Helvetica Neue'; font-size: 13px;"><br class=""></div><div style="font-family: 'Helvetica Neue'; font-size: 13px;"></div></div></div></div><div class=""><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;" class="">____</div></div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;" class=""><br class=""></div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;" class=""><div style="font-family: 'Helvetica Neue'; font-size: 13px;">Last up, the rule that all enum cases should be nouns didn’t seem to fit here:</div><div class=""><br class=""></div></div></div></div><div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo; color: rgb(88, 126, 168);" class=""><div style="margin: 0px; font-size: 10.5px; line-height: normal;" class=""><span style="font-variant-ligatures: no-common-ligatures; color: #323e7d" class=""> public</span><span style="font-variant-ligatures: no-common-ligatures; color: #000000" class=""> </span><span style="font-variant-ligatures: no-common-ligatures; color: #323e7d" class="">enum</span><span style="font-variant-ligatures: no-common-ligatures; color: #000000" class=""> ResourceEvent: </span>CustomStringConvertible<span style="font-variant-ligatures: no-common-ligatures; color: #000000" class=""> {</span></div></div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;" class=""><span style="font-size: 10.5px;" class=""> </span><span style="font-size: 10.5px; color: rgb(50, 62, 125);" class="">case</span><span style="font-size: 10.5px;" class=""> ObserverAdded</span></div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo; min-height: 12px;" class=""><span style="font-size: 10.5px;" class=""> </span><span style="font-size: 10.5px; color: rgb(50, 62, 125);" class="">case</span><span style="font-size: 10.5px;" class=""> Requested</span></div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo; min-height: 12px;" class=""><span style="font-size: 10.5px;" class=""> </span><span style="font-size: 10.5px; color: rgb(50, 62, 125);" class="">case</span><span style="font-size: 10.5px;" class=""> RequestCancelled</span></div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo; min-height: 12px;" class=""> <span style="font-size: 10.5px; color: rgb(50, 62, 125);" class="">case</span><span style="font-size: 10.5px;" class=""> NewData(NewDataSource)</span></div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo; min-height: 12px;" class=""> <span style="font-size: 10.5px; color: rgb(50, 62, 125);" class="">case</span><span style="font-size: 10.5px;" class=""> NotModified</span></div><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo; min-height: 12px;" class=""> <span style="font-size: 10.5px; color: rgb(50, 62, 125);" class="">case</span><span style="font-size: 10.5px;" class=""> Error</span></div><div class=""><div style="margin: 0px; font-size: 10.5px; line-height: normal; font-family: Menlo;" class=""> }</div></div><div class=""><br class=""></div></div><div>Noun alternatives such as “ObserverAddition” and “RequestStart” somehow come with more mental friction.</div><div><br class=""></div><div>Again, I don’t have a rule to propose here — and in these cases, we may just have to say “this is why guidelines are guidelines, not laws,” and leave it at that. Or someone can propose better names, which would be awesome!</div><div><br class=""></div><div>Cheers,</div><div><br class=""></div><div>Paul</div><div><br class=""></div><div><br class=""></div><div><br class=""></div></body></html>