When to use argument labels (a new approach)

Evolution Discussion
47

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@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@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution