When to use argument labels (a new approach)

Evolution Discussion
161

In the case of this particular API, it's OK, because normal users can
always call copy().

In general, when importing APIs whose base name would end in a
preposition and whose only parameter would have a default, we could
choose to:

1. drop the preposition.
2. drop the default
3. allow the preposition to dangle when no argument is passed
4. complicate the rules to allow the preposition to migrate inside the
   parens
5. change the rules so that the preposition is always inside the parens

I think #1, #2, #3, and #4 all correspond to guidelines that end up
deterring people from evolving APIs by adding a default for the first
argument when it's part of a prepositional phrase.

Remember the problem with #5: move(toX: x, y: y) is ugly. On the other
hand, there not so many of these APIs, there are ways to (manually)
smooth such an API, e.g. move(to: (x,y)) or move(to: Point(x,y)), and
that is the only way to unambiguously distribute a preposition across
arguments in a case where it doesn't apply to *all* arguments:

  move(to: (x,y), by: .Sliding)

On the other other hand, I don't find move(toX: x, y: y, by: .Sliding)
to be ambiguous in practice, just a bit ugly.

So maybe prepositions should go inside parentheses.

···

on Mon Feb 08 2016, Matthew Judge <swift-evolution@swift.org> wrote:

Agree that basing the preposition location on whether there is a
default value is unfortunate. The problem is "Zone" is not
redundant/needless when calling it with the default value.

copyWith()

If I were asking "what zone?" Ok it's the default zone, but I'm just asking "with what?"

On Feb 7, 2016, at 10:48, Dave Abrahams via swift-evolution >> <swift-evolution@swift.org> wrote:

on Sat Feb 06 2016, Douglas Gregor <swift-evolution@swift.org> wrote:

On Feb 6, 2016, at 10:08 PM, Dave Abrahams via swift-evolution >>>> <swift-evolution@swift.org> wrote:

on Sat Feb 06 2016, Thorsten Seitz <swift-evolution@swift.org> wrote:

So the preposition should move into the argument label if the argument is optional?

copy(withZone: zone = nil)

That's a good idea.

It seems unfortunate that the placement of the preposition should
change depending on whether there is a default argument or not,
especially since it is reasonable to imagine that an API evolves to
gain a default argument later on.

You're right; it would complicate the rules significantly, too.

   - Doug

-Thorsten

Am 06.02.2016 um 14:45 schrieb Matthew Judge via swift-evolution >>>>>> <swift-evolution@swift.org>:

Very first method

copyWith(zone: Zone = nil)

can be called as

copyWith()

I'm assuming this is still something we don't want right?

On Feb 6, 2016, at 02:16, Douglas Gregor via swift-evolution >>>>>>> <swift-evolution@swift.org> wrote:

On Feb 5, 2016, at 1:32 PM, 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:

[snip goals]

P.S. Doug is presently working on generating new importer results, based
  on these guidelines, for your perusal. They should be ready soon.

Here’s a link:

   Split first selector piece into base name/first argument label. by DougGregor · Pull Request #10 · apple/swift-3-api-guidelines-review · GitHub

Feedback welcome!

   - Doug

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

--
-Dave

162

Agree that basing the preposition location on whether there is a default value is unfortunate. The problem is "Zone" is not redundant/needless when calling it with the default value.

copyWith()

If I were asking "what zone?" Ok it's the default zone, but I'm just asking "with what?"

Honestly, I don't think `-copyWithZone:` is a good API to use as an exemplar. It's a non-mutating method with an imperative name, which is not usually done even in Objective-C, let alone Swift. In fact, it's so unusual that it doesn't even have the same retaining conventions as most other methods.

I would consider special-casing `-copyWithZone:` to import as `copied(to:)`. (The mutable variant should be `mutablyCopied(to:)`.) `to` is used here because, when there *is* a zone in use, the new copy is made in that zone. Alternatively, you could think of the zone as an option, in which case it'd be `copied(zone:)`. Plain `-copy` should simply be hidden; it's a convenience wrapper around `-copyWithZone:`, and one that's unnecessary if the zone argument carries a default value.

···

--
Brent Royal-Gordon
Architechies

163

Agree that basing the preposition location on whether there is a
default value is unfortunate. The problem is "Zone" is not
redundant/needless when calling it with the default value.

copyWith()

If I were asking "what zone?" Ok it's the default zone, but I'm just asking "with what?"

Honestly, I don't think `-copyWithZone:` is a good API to use as an
exemplar. It's a non-mutating method with an imperative name, which is
not usually done even in Objective-C, let alone Swift.

Arguably you can read it as a noun-phrase.

In fact, it's so unusual that it doesn't even have the same retaining
conventions as most other methods.

In Swift/under ARC it does.

I would consider special-casing `-copyWithZone:` to import as
`copied(to:)`. (The mutable variant should be `mutablyCopied(to:)`.)
`to` is used here because, when there *is* a zone in use, the new copy
is made in that zone. Alternatively, you could think of the zone as an
option, in which case it'd be `copied(zone:)`. Plain `-copy` should
simply be hidden; it's a convenience wrapper around `-copyWithZone:`,
and one that's unnecessary if the zone argument carries a default
value.

Your points about copyWithZone being unusual are well-taken, but it
still presents a set of API naming issues that are fairly common. If
you prefer, you can imagine that encodeWithCoder had a default argument.
Any method called xxxWithOptions would be a realistic example (though I
can't remember a specific one offhand), because all option sets are
getting an empty default.

···

on Mon Feb 08 2016, Brent Royal-Gordon <swift-evolution@swift.org> wrote:

--
-Dave