[swift-evolution] API Guidelines Update

[Dave Abrahams]

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