[swift-evolution] When to use argument labels, part DEUX (was: when to use argument labels (a new approach))
Radosław Pietruszewski
radexpl at gmail.com
Mon Feb 8 14:46:18 CST 2016
Dave,
First of all, thank you for enduring our nitpicks and complaints and continuing to explore the subject :) I think we’re all better off for it, and getting closer to the solution with each iteration.
You asked:
> 1. I'm not expecting these guidelines to make everybody optimally happy,
> all the time, but they shouldn't be harmful. Are there any cases for
> which they produce results you couldn't live with?
And I think, by this standard, the guidelines you proposed seem to be a success. Looking through Doug’s diffs, I see a lot of method names that I don’t *love*, but I couldn’t find something I would hate.
* * *
> - subscript (key: String) -> CKRecordValue? + subscript (keyedSubscript key: String) -> CKRecordValue?
Huh?
> - func dateBySettingUnit(unit: CalendarUnit, value v: Int, of date: Date, options opts: CalendarOptions = []) -> Date?
> + func dateBy(settingUnit unit: CalendarUnit, value v: Int, of date: Date, options opts: CalendarOptions = []) -> Date?
That doesn’t look like the intended result...
— Radek
> On 05 Feb 2016, at 22:32, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
>
>
> Given all the awesome feedback I've gotten on this thread, I went back
> to the drawing board and came up with something new; I think this one
> works. The previously-stated goals still apply:
>
> * describe when and where to use argument labels
> * require labels in many of the cases people have asked for them
> * are understandable by humans (this means relatively simple)
> * preserve important semantics communicated by existing APIs.
>
> Please keep in mind that it is a non-goal to capture considerations we
> think have a bearing on good names (such as relatedness of parameters):
> it's to create simple guidelines that have the right effect in nearly
> all cases.
>
> A. When arguments can't be usefully distinguished from one another, none
> should have argument labels, e.g. min(x,y), zip(x,y,z).
>
> B. Otherwise,
>
> 1. At the call site, a first parameter that has no argument label must
> form part of a grammatical phrase that starts with the basename, less
> any trailing nouns.
>
> print(x)
> a.contains(b)
> a.mergeWith(b)
> a.addGestureRecognizer(x)
> ^~~~~~~~~~~~~~~~~ trailing noun
>
> This phrase must have the correct semantic implications, so, e.g.
>
> a.dismiss(b) // no, unless a is really dismissing b
> a.dismissAnimated(b) // no, not grammatical
> a.dismiss(animated: b) // yes, using a label
>
> 2. If the first argument is part of a prepositional phrase, put the
> parenthesis immediately after the preposition.
>
> a.encodeWith(b)
> a.moveFrom(b, to: c)
>
> Thus, if words are required for any reason between the preposition
> and the first argument, they go into the first argument label.
>
> a.tracksWith(mediaType: b, composer: c)
> a.moveTo(x: 22, y: 99)
>
> Notes:
>
> a. I would recommend prepositions other than "with" in nearly all
> cases, but that's not the point of these rules.
> b. I can understand the aesthetic appeal of
>
> a.move(from: b, to: c)
>
> but I believe it is not a clear enough improvement to justify
> additional complexity in the guidelines.
>
> Questions:
>
> 1. I'm not expecting these guidelines to make everybody optimally happy,
> all the time, but they shouldn't be harmful. Are there any cases for
> which they produce results you couldn't live with?
>
> 2. Are there any cases where you'd be confused about how to apply these
> guidelines?
>
> Thanks in advance for all your valuable input!
>
> P.S. Doug is presently working on generating new importer results, based
> on these guidelines, for your perusal. They should be ready soon.
>
> --
> -Dave
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution
More information about the swift-evolution
mailing list