[swift-evolution] API Guidelines Update

[David Owens II]

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