<html><head><meta http-equiv="content-type" content="text/html; charset=utf-8"></head><body dir="auto"><div><span style="background-color: rgba(255, 255, 255, 0);">I think part of where the current guidelines struggle is the ambiguity of the term "argument label" so just for the sake of discussion I'm going to define terms to be explicit (not saying these are precisely the right terms).</span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">- External parameter names: names used to refer to parameters at the use site</span></div><div><span style="background-color: rgba(255, 255, 255, 0);">a.moveTo(x: 1, y: 2) // external parameter names are "x" and "y"</span></div><div><span style="background-color: rgba(255, 255, 255, 0);">a.addGestureRecognizer(b) // does not have an external parameter name</span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">- Argument labels: words used to describe the argument being passed in</span></div><div><div><span style="background-color: rgba(255, 255, 255, 0);">a.moveTo(x: 1, y: 2) // argument labels are "x" and "y"</span></div><div><span style="background-color: rgba(255, 255, 255, 0);">a.addGestureRecognizer(b) // argument label is "GestureRecognizer"</span></div></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">Both of these are referred to as "argument labels" in the guidelines and most of the discussion, but they are slightly different (though overlapping) things. For instance, B.1 refers to "external parameter names" and B.2 refers to "argument labels"</span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">I think my distinction between these terms makes the guidelines simpler with fewer caveats:</span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">1. Prune needless and redundant words from the argument labels (i.e. remove any word that can be removed without confusing the semantic intent)</span></div><div><span style="background-color: rgba(255, 255, 255, 0);">2. If the method reads as part of a grammatical phrase, prefer to locate the first argument label as part of the base name instead of as an external parameter name.</span></div><div><span style="background-color: rgba(255, 255, 255, 0);">Special Cases/Exceptions:</span></div><div><span style="background-color: rgba(255, 255, 255, 0);">a. Arguments with a default value should use an external parameter name</span></div><div><span style="background-color: rgba(255, 255, 255, 0);">b. Arguments with similar semantic importance should be treated the same (use external parameter names for argument labels or don't label any)</span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">Not saying these are right/perfect, but I do think the distinction of guidelines for argument labels and external parameter will make the rules simpler, clearer, and more consistent. </span><span style="background-color: rgba(255, 255, 255, 0);">(Everything below here is applying these rules to each of the examples used in Dave's original post.)</span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">print(x) // Guideline 1 prunes argument label</span></div><div><span style="background-color: rgba(255, 255, 255, 0);">a.contains(b) // Same</span></div><div><span style="background-color: rgba(255, 255, 255, 0);">a.mergeWith(b) // Guideline 1 shortens argument label "WithCollection" to "With"</span></div><div><span style="background-color: rgba(255, 255, 255, 0);">// Guideline 2 moves "With" into the base name</span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">a.addGestureRecognizer(x)</span></div><div><span style="background-color: rgba(255, 255, 255, 0);">// Guideline 1 does NOT prune "GestureRecognizer" because it would change the semantic meaning</span></div><div><span style="background-color: rgba(255, 255, 255, 0);">// Guideline 2 moves it into the base name</span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">- the following 3 examples from the original are treated the same under these rules, for the same reasons mentioned</span></div><div><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><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></blockquote><blockquote type="cite"><blockquote type="cite"><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></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> a.dismiss(animated: b) // yes, using a label</span></font></blockquote></blockquote></blockquote><blockquote type="cite"></blockquote></blockquote></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">a.encodeWith(b) // Guideline 1 shortens argument label "WithCoder" to "With"</span></div><div><span style="background-color: rgba(255, 255, 255, 0);">// Guideline 2 says put "With" to the base name</span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">a.moveFrom(b, to: c) // Only change to the results of Dave's examples</span></div><div><span style="background-color: rgba(255, 255, 255, 0);">// Guideline 1 shortens "fromScene" to "from" and "toScene" to "to"</span></div><div><span style="background-color: rgba(255, 255, 255, 0);">// Exception (b) prevents Guideline 2 from moving "from" into the base name</span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">* Note that I believe the only change to these guidelines required to recover the behavior of Dave's original guidelines is modifying Exception (b) to language similar to Dave's A.</span></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">- the following two examples would be covered by Exception (b) as well</span></div><div><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><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></blockquote><blockquote type="cite"><blockquote type="cite"><blockquote type="cite"><font color="#000000"><span style="background-color: rgba(255, 255, 255, 0);"> a.moveTo(x: 22, y: 99)</span></font></blockquote></blockquote></blockquote></blockquote></div><div><span style="background-color: rgba(255, 255, 255, 0);"><br></span></div><div><span style="background-color: rgba(255, 255, 255, 0);">Sorry for the long email... Hopefully it's somewhat useful.</span></div></body></html>