[swift-evolution] When to use argument labels (a new approach)
Charles Kissinger
crk at akkyra.com
Thu Feb 4 12:06:20 CST 2016
> On Feb 3, 2016, at 3:54 PM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
>
>
> on Wed Feb 03 2016, Charles Kissinger <swift-evolution at swift.org> wrote:
>
>> What I was getting at there is that
>> ‘a.tracksHavingMediaTypeWaxCylinder’ doesn’t seem like a sentence to
>> me. It is a clause, no doubt, but doesn’t seem to be an independent
>> one.
>
> Agh, you're right. If only we used verbs in these cases... but that is
> a whole nother discussion. I guess I'll have to say "clause" instead of
> "sentence," which really sucks. Or I can say there's an implied "get"
> at the front if there's no verb. bleah.
The implied ‘get' approach doesn’t seem too bad to me. Would it suffice to stick with ‘sentence' and add the condition that if there is an implied ‘get' or ‘set' that would form a sentence, then Rule 1 still applies?
I can’t think of any cases where people use an implied verb other than something in the 'get' family (find, acquire, etc.). Looking through my own code, the very concise set of rules in your original post work perfectly (IMO) with the exception of the “missing get” problem.
—CK
>
>> It was unclear to me whether it didn’t fit the Rule 1 criteria for
>> that reason, but Rule 2 was specifically including it, or whether I
>> just wasn’t seeing the “sentence-like” nature of it.
>>
>> —CK
>>
>>>
>>>> —CK
>>>>
>>>>> On Feb 2, 2016, at 4:32 PM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
>>>>>
>>>>>
>>>>> This thread is related to the review of new API guidelines, but it's not
>>>>> a review thread; it's exploratory. The goal is to come up with
>>>>> guidelines that:
>>>>>
>>>>> * describe when and where to use argument labels
>>>>> * require labels in many of the cases people have asked for them
>>>>> * are understandable by humans
>>>>> * preserve important semantics communicated by existing APIs.
>>>>>
>>>>> Here's what I'm thinking
>>>>>
>>>>> 1. If and only if the first argument could complete a sentence*
>>>>> beginning in the base name and describing the primary semantics of
>>>>> the call, it gets no argument label:
>>>>>
>>>>> a.contains(b) // b completes the phrase "a contains b"
>>>>> a.mergeWith(b) // b completes the phrase "merge with b"
>>>>>
>>>>> a.dismiss(animated: b) // "a, dismiss b" is a sentence but
>>>>> // doesn't describe the semantics at all,
>>>>> // thus we add a label for b.
>>>>>
>>>>> a.moveTo(x: 300, y: 400) // "a, move to 300" is a sentence
>>>>> // but doesn't describe the primary
>>>>> // semantics, which are to move in both
>>>>> // x and y. Thus, x gets a label.
>>>>>
>>>>> a.readFrom(u, ofType: b) // "a, read from u" describes
>>>>> // the primary semantics, so u gets no
>>>>> // label. b is an
>>>>> // option that tunes the primary
>>>>> // semantics
>>>>>
>>>>> [Note that this covers all the direct object cases and, I believe,
>>>>> all the default argument cases too, so maybe that exception can be
>>>>> dropped. We still need the exceptions for full-width type
>>>>> conversions and indistinguishable peers]
>>>>>
>>>>> Note: when there is a noun in the base name describing the role of the
>>>>> first argument, we skip it in considering this criterion:
>>>>>
>>>>> a.addObserver(b) // "a, add b" completes a sentence describing
>>>>> // the semantics. "Observer" is omitted in
>>>>> // making this determination.
>>>>>
>>>>> * We could say "clause" here but I think making it an *independent*
>>>>> clause doesn't rule out any important use-cases (see
>>>>> https://web.cn.edu/kwheeler/gram_clauses_n_phrases.html) and at that
>>>>> point, you might as well say "sentence," which is a more
>>>>> universally-understood term.
>>>>>
>>>>> 2. Words that describe attributes of an *already-existing* instance
>>>>> should go in the base name rather than in a label:
>>>>>
>>>>> a.tracksHavingMediaType("Wax Cylinder") // yes
>>>>> a.removeFirstTrackHavingMediaType("BetaMax") // yes
>>>>>
>>>>> a.tracks(mediaType: "Wax Cylinder") // no
>>>>> a.removeFirstTrack(havingMediaType: "BetaMax") // no
>>>>>
>>>>> [yes, we could use "With" instead of "Having", but it's more
>>>>> ambiguous]
>>>>>
>>>>> Words that describe attributes of an instance *to be created* should
>>>>> go in argument labels, rather than the base name (for parity with
>>>>> initializers):
>>>>>
>>>>> AudioTrack(mediaType: "BetaMax") // initializer
>>>>> trackFactory.newTrack(mediaType: "Wax Cylinder") // yes
>>>>>
>>>>> trackFactory.newTrackWithMediaType("Wax Cylinder") // no
>>>>>
>>>>> 3. (this one is separable) When the first argument is the *name* or
>>>>> *identifier* of the subject in the base name, do not label it or
>>>>> describe it in the base name.
>>>>>
>>>>> a.transitionToScene(.GreatHall) // yes
>>>>> a.transitionToSceneWithIdentifier(.GreatHall) // no
>>>>>
>>>>> let p = someFont.glyph("propellor") // yes
>>>>> let p = someFont.glyphWithName("propellor") // no
>>>>> let p = someFont.glyph(name: "propellor") // no
>>>>>
>>>>> Thoughts?
>>>>>
>>>>> --
>>>>> -Dave
>>>>>
>>>>> _______________________________________________
>>>>> swift-evolution mailing list
>>>>> swift-evolution at swift.org
>>>>> https://lists.swift.org/mailman/listinfo/swift-evolution
>>>>
>>>> _______________________________________________
>>>> swift-evolution mailing list
>>>> swift-evolution at swift.org
>>>> https://lists.swift.org/mailman/listinfo/swift-evolution
>>>
>>> --
>>> -Dave
>>>
>>> _______________________________________________
>>> swift-evolution mailing list
>>> swift-evolution at swift.org
>>> https://lists.swift.org/mailman/listinfo/swift-evolution
>>
>> _______________________________________________
>> swift-evolution mailing list
>> swift-evolution at swift.org
>> https://lists.swift.org/mailman/listinfo/swift-evolution
>
> --
> -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