<html><body style="word-wrap: break-word; -webkit-nbsp-mode: space; -webkit-line-break: after-white-space;" class=""><br class=""><blockquote type="cite" class="">On Jan 30, 2016, at 9:54 PM, Dave Abrahams via swift-evolution <<a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a>> wrote:<br class=""><br class="">on Fri Jan 29 2016, Paul Cantrell <<a href="mailto:swift-evolution@swift.org" class="">swift-evolution@swift.org</a>> wrote:<br class=""><br class=""><blockquote type="cite" class="">I do worry that these</blockquote><blockquote type="cite" class="">proposed guidelines pack too much significance into the vagaries of<br class="">English grammar, which (as we’ve found out on this thread) is an<br class="">inconsistent and fickle friend. I’m personally in favor of charging<br class="">ahead with that quixotic venture nonetheless, but I do worry a bit<br class="">that the guidelines as stated are too narrowly stated in all the<br class="">places where grammar is involved.<br class=""></blockquote><br class="">Understood. It would be nice to be able to say “just do what makes<br class="">sense,” but the downside is that you lose regularity and you lose<br class="">developer hours agonizing over trivia. The downside of API guidelines<br class="">is that they restrain you from doing what you want to do... and the<br class="">upside is that they restain you from doing whatever you want to do. ;-)<br class=""></blockquote><br class=""><div class="">An escape clause would help strike the balance: let the guidelines be as narrow as they are, but include a “guidelines are not laws” remark that gives teams permission to make <i class="">carefully considered</i> guideline overrides. This would prevent the “but it says so right here we must not deviate” vs. “but that injures clarity in our situation” argument within teams.</div><div class=""><br class=""></div><div class="">It seems to me that the first item under “Fundamentals,” maybe the first two, have a different order of importance than the rest of the document: “Clarity at the point of use is your most important goal. Clarity is more important than brevity.” That’s the Bill of Rights, as it were, and the rest of the guidelines are federal laws. Sometimes, in a particular situation, specific guidelines will come into conflict with clarity. You’ve written the guidelines to try to minimize that happening, but when it does, it’s clarity that should prevail.</div><div class=""><br class=""></div><div class="">…and I imagine we’d all agree on that, but having the guidelines explicitly say as much would prevent unnecessary agonizing.</div><div class=""><br class=""></div><div class="">Cheers,</div><div class=""><br class=""></div><div class="">Paul</div><div class=""><br class=""></div></body></html>