[swift-evolution] API Guidelines Update

[Rudolf Adamkovic]

Oh, all right then.

R+

Sent from my iPhone

> On 25 Feb 2016, at 18:17, Dave Abrahams <dabrahams at 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 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
> 
> -- 
> -Dave