[swift-evolution] API Guidelines Update

[Rudolf Adamkovič]

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?

R+

> On 25 Feb 2016, at 02:10, David Owens II via swift-evolution <swift-evolution at 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 at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution