1

I agree that positioning the preposition depending on whether a default value is present is unfortunate, but I don't agree that it would complicate the rules significantly as it just adds a very simple special case for one rule.

Is the problem that it complicates API evolvement significant enough to outweigh the advantage of this rule?

Closure arguments with default values won't profit from it if written as trailing closure, of course.

No good idea how to remedy that (trailing argument label?? probably not).

-Thorsten

···

Am 08. Februar 2016 um 12:47 schrieb Matthew Judge via swift-evolution swift-evolution@swift.org:

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:

https://github.com/apple/swift-3-api-guidelines-review/pull/10/files

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
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?"

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

2

I agree that positioning the preposition depending on whether a
default value is present is unfortunate, but I don't agree that it
would complicate the rules significantly as it just adds a very simple
special case for one rule.

Heh, but then people will really demand a special case for move(from: a,

Is the problem that it complicates API evolvement significant enough
to outweigh the advantage of this rule?

That's one problem. I think we should also be concerned about rules
that create a feeling of non-uniformity and un-predictability across
code. For example, you don't want to see something like this:

       removeAllBricks(having: .CrackleGlazeFinish)

       removeAllBeamsHaving(.RottenWood)

Closure arguments with default values won't profit from it if written
as trailing closure, of course.

No good idea how to remedy that (trailing argument label?? probably not).

I think that's a whole 'nother bag o' worms, and, yes, some language
syntax might be needed. IOW, the issue goes beyond mere guidelines.

···

on Mon Feb 08 2016, Thorsten Seitz <swift-evolution@swift.org> wrote:
to: b)

-Thorsten

Am 08. Februar 2016 um 12:47 schrieb Matthew Judge via swift-evolution > <swift-evolution@swift.org>:

    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

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

--
-Dave

3

> I agree that positioning the preposition depending on whether a
> default value is present is unfortunate, but I don't agree that it
> would complicate the rules significantly as it just adds a very simple
> special case for one rule.

Heh, but then people will really demand a special case for move(from: a,
to: b)

> Is the problem that it complicates API evolvement significant enough
> to outweigh the advantage of this rule?

That's one problem. I think we should also be concerned about rules
that create a feeling of non-uniformity and un-predictability across
code. For example, you don't want to see something like this:

       removeAllBricks(having: .CrackleGlazeFinish)

       removeAllBeamsHaving(.RottenWood)

I just thought of another point in favor of prepositions going inside
parentheses: verbs that take an optional indirect object, expressed as an
overload.

protocol Message {
  // Stores the whole message
  func store(toCoreDataEntity tableName: String)
  func store(toUserDefaults key: String)

  // Stores only a single field within the message
  func store(field: String, toCoreDataEntity tableName: String)
  func store(field: String, toUserDefaults key: String)
}

protocol RenderLayer {
  // Moves the whole layer
  func move(toDOMElement element: DOMElement, edge: Edge)

  // Moves an element within the render layer
  func move(elementWithID id: String, toDOMElement element, edge: Edge)
  func move(element element: DOMElement, toDOMElement element, edge: Edge)
}

With preposition-inside-parentheses, there's a nice symmetry between these
API calls:

move(toDOMElement: table, edge: .Bottom) // Whole layer
move(elementWithID: "#nav", toDOMElement: table, edge: .Bottom) // Just
one element

With preposition-outside-parentheses, they become pretty awkward:

moveTo(DOMElement: table, edge: .Bottom)
move(elementWithID: "#nav", toDOMElement: table, edge: .Bottom) // Why
different base name?
moveTo(DOMElement: table, edge: .Bottom, elementWithID: "#nav") // What's
getting moved?
moveTo(DOMElement: table, edge: .Bottom, onlyTheElementWithID: "#nav") //
Works, but wordy

None of this is what I'd consider a deal-breaker, and I know the review
period has ended, but if a decision hasn't been made yet and you're on the
fence, please consider. :-)

···

On Mon, Feb 8, 2016 at 5:23 AM, Dave Abrahams via swift-evolution < swift-evolution@swift.org> wrote:

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

> Closure arguments with default values won't profit from it if written
> as trailing closure, of course.
>
> No good idea how to remedy that (trailing argument label?? probably not).

I think that's a whole 'nother bag o' worms, and, yes, some language
syntax might be needed. IOW, the issue goes beyond mere guidelines.

> -Thorsten
>
> Am 08. Februar 2016 um 12:47 schrieb Matthew Judge via swift-evolution > > <swift-evolution@swift.org>:
>
> 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
>
> _______________________________________________
> 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

4

Thanks for your insight, Jonathan. Yes, the review period is formally
over but we've now entered the “what, exactly, do we do with the results
of this discussion?” phase. More discussion is certainly welcome at any
time.

···

on Mon Feb 08 2016, Jonathan Tang <jonathan.d.tang-AT-gmail.com> wrote:

None of this is what I'd consider a deal-breaker, and I know the review
period has ended, but if a decision hasn't been made yet and you're on the
fence, please consider. :-)

--
-Dave

5

The current set of rules are causing methods with completion handlers to be imported inconsistently. Sometimes the method name includes With, but sometimes it does not.

For example,

// no With
- func exportAsynchronouslyWithCompletionHandler(handler: () -> Void)
+ func exportAsynchronously(completionHandler handler: () -> Void)

// yes With
- func determineCompatibleFileTypesWithCompletionHandler(handler: ([String]) -> Void)
+ func determineCompatibleFileTypesWith(completionHandler handler: ([String]) -> Void)

// no With
- func finishWritingWithCompletionHandler(handler: () -> Void)
+ func finishWriting(completionHandler handler: () -> Void)

// no and yes With
- func savePresentedItemChangesWithCompletionHandler(completionHandler: (Error?) -> Void)
- func accommodatePresentedItemDeletionWithCompletionHandler(completionHandler: (Error?) -> Void)
+ func savePresentedItemChanges(completionHandler completionHandler: (Error?) -> Void)
+ func accommodatePresentedItemDeletionWith(completionHandler completionHandler: (Error?) -> Void)

Perhaps eliminating “with” before parentheses in these cases is the way to go, especially since many completion handlers are good candidates to have default values, as suggested by the Guidelines:

extension Document {
  func close(completionHandler completion: ((Bool) -> Void)? = nil)
}

My apologies if this is irrelevant or has already been discussed!

Mila

···

On Feb 8, 2016, at 10:31 AM, Dave Abrahams via swift-evolution <swift-evolution@swift.org> wrote:

on Mon Feb 08 2016, Jonathan Tang <jonathan.d.tang-AT-gmail.com> wrote:

None of this is what I'd consider a deal-breaker, and I know the review
period has ended, but if a decision hasn't been made yet and you're on the
fence, please consider. :-)

Thanks for your insight, Jonathan. Yes, the review period is formally
over but we've now entered the “what, exactly, do we do with the results
of this discussion?” phase. More discussion is certainly welcome at any
time.

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