API Guidelines Update

Is there a reason we can’t use the type system to do the work for us? So, instead of:

A.trim(B)
A.trimming(B)

… we would have:

A.trim(B)
A.trim(B) -> A

In cases like “dropFirst” where the function returns something, we would use an “out” parameter:

A.dropFirst(B)
A.dropFirst(B, out: X)

In this case X is the dropped element.

So, this approach would require implementing “out” parameters (in addition to “inout” we have today).

I’m no expert and I’m probably missing something here. Is there additional ambiguity I’m not aware of?

Hi Rudolf,

This possibility has been discussed in earlier threads. I suggest
you read those, then ask again if you still have questions.

Thanks!

···

on Thu Feb 25 2016, Rudolf Adamkovič <salutis-AT-me.com> wrote:

R+

On 25 Feb 2016, at 02:10, David Owens II via swift-evolution <swift-evolution@swift.org> wrote:

The noun tells you the object that will be worked with.

`stringByTrimmingCharactersInSet(_:)` - return a string by trimming characters in set

`trimCharactersInSet(_:)`, `trim(_:)`, and `trimming(_:)` all read:
return myself by trimming characters in set; there is no noun, so it
is implied that it's the caller of the function.

I disagree. The first two form imperative verb phrases, and do not imply
to me that anything will be returned. Furthermore, I think for anyone
who works in a language with mutation it is natural to assume that
imperative-verb-phrase methods might mutate the receiver and return
nothing. This is not a new idea; Cocoa already does things this way.

"return myself" was a poor word choice; "perform on myself" would have been better and more accurate.

There are many contexts where chaining is preferred, so
foo.trim().trim().filter().trim() would be a valid use case. That
was the sample running in my head when I wrote that section and why
I wrote "return myself".

I also agree with you that an imperative verb phrase implies
mutation, and I think that part is covered in the guidelines well.

The first two guidelines already captures this sentiment as well:

1. "Those without side-effects should read as noun phrases".
2. "Those with side-effects should read as imperative verb phrases."

I know what the guidelines say and what they're supposed to mean, and I
can't see how they support your point in any way. Neither “trimming b”
nor “a trimming b” is an imperative verb phrase in English. It is
always a noun phrase.

True, `trimming` is not an imperative verb phrase; strike it from my example list.

Yes, that's true. You have to think ahead about API evolution if you
don't want to break users. That goes for naming as well as anything
else. If I said, “related APIs should form a distinguishable family,”
you probably wouldn't argue (would you?) but that guideline could lead
to exactly the same sequence of events.

Maybe, but I don't necessarily think that grouping mutable and
non-mutable into the same family is the right approach.

-David

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

--
-Dave

Oh, all right then.

R+

···

Sent from my iPhone

On 25 Feb 2016, at 18:17, Dave Abrahams <dabrahams@apple.com> wrote:

on Thu Feb 25 2016, Rudolf Adamkovič <salutis-AT-me.com> wrote:

Is there a reason we can’t use the type system to do the work for us? So, instead of:

A.trim(B)
A.trimming(B)

… we would have:

A.trim(B)
A.trim(B) -> A

In cases like “dropFirst” where the function returns something, we would use an “out” parameter:

A.dropFirst(B)
A.dropFirst(B, out: X)

In this case X is the dropped element.

So, this approach would require implementing “out” parameters (in addition to “inout” we have today).

I’m no expert and I’m probably missing something here. Is there additional ambiguity I’m not aware of?

Hi Rudolf,

This possibility has been discussed in earlier threads. I suggest
you read those, then ask again if you still have questions.

Thanks!

R+

On 25 Feb 2016, at 02:10, David Owens II via swift-evolution <swift-evolution@swift.org> wrote:

The noun tells you the object that will be worked with.

`stringByTrimmingCharactersInSet(_:)` - return a string by trimming characters in set

`trimCharactersInSet(_:)`, `trim(_:)`, and `trimming(_:)` all read:
return myself by trimming characters in set; there is no noun, so it
is implied that it's the caller of the function.

I disagree. The first two form imperative verb phrases, and do not imply
to me that anything will be returned. Furthermore, I think for anyone
who works in a language with mutation it is natural to assume that
imperative-verb-phrase methods might mutate the receiver and return
nothing. This is not a new idea; Cocoa already does things this way.

"return myself" was a poor word choice; "perform on myself" would have been better and more accurate.

There are many contexts where chaining is preferred, so
foo.trim().trim().filter().trim() would be a valid use case. That
was the sample running in my head when I wrote that section and why
I wrote "return myself".

I also agree with you that an imperative verb phrase implies
mutation, and I think that part is covered in the guidelines well.

The first two guidelines already captures this sentiment as well:

1. "Those without side-effects should read as noun phrases".
2. "Those with side-effects should read as imperative verb phrases."

I know what the guidelines say and what they're supposed to mean, and I
can't see how they support your point in any way. Neither “trimming b”
nor “a trimming b” is an imperative verb phrase in English. It is
always a noun phrase.

True, `trimming` is not an imperative verb phrase; strike it from my example list.

Yes, that's true. You have to think ahead about API evolution if you
don't want to break users. That goes for naming as well as anything
else. If I said, “related APIs should form a distinguishable family,”
you probably wouldn't argue (would you?) but that guideline could lead
to exactly the same sequence of events.

Maybe, but I don't necessarily think that grouping mutable and
non-mutable into the same family is the right approach.

-David

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

--
-Dave