[swift-evolution] [Pitch] Improve the API Design Guidelines about protocol naming

[Gmail]

Sorry if my original reply didn’t come across as neutral as I had hoped. I actually like the Protocol suffix and have used it when the name I wanted to use was already taken by a concrete type. 

I’m not sure yet if a Protocol suffix would “always” be the right choice when a protocol can't be named with a noun, or with an `able`, `ible`, or `ing` suffix. There might not be that many cases. 

How about a guideline that only covers the case when a protocol coexists with a concrete type? Maybe something like:

 + When a protocol and a concrete type contest for the same name, the protocol should be named using the suffix `Protocol` (e.g. `IteratorProtocol`).

That would both apply to the Range protocol naming, and would follow the the established pattern set by IteratorProtocol, LazySequenceProtocol which seem to have come from [SE-0006](https://github.com/apple/swift-evolution/blob/master/proposals/0006-apply-api-guidelines-to-the-standard-library.md):

> Strip `Type` suffix from protocol names. In a few special cases this means adding a `Protocol` suffix to get out of the way of type names that are primary (though most of these we expect to be obsoleted by Swift 3 language features).

David

> On 20 Apr 2017, at 18:55, Jordan Rose <jordan_rose at apple.com> wrote:
> 
> Yeah, I wasn't trying to take a side, just identifying where David might have heard "Protocol" in an official Apple presentation. I'm staying out of this one. :-)
> 
> Jordan
> 
>> On Apr 20, 2017, at 00:21, Gwendal Roué <gwendal.roue at gmail.com <mailto:gwendal.roue at gmail.com>> wrote:
>> 
>> Well, IteratorProtocol, LazySequenceProtocol weren't imported from ObjC.
>> 
>> They set a precedent for the -Protocol suffix.
>> 
>> Now, even if you don't like RangeProtocol, this doesn't make RangeExpression better.
>> 
>> "Expression" and `1...` don't belong to the same level of the language: one is a concept of that belongs to the compiler, when the other is a plain value used in a program:
>> 
>> When a program does `1 + 2`, it both sums two integers, and builds a expression from two other expressions and an operator. Both are true. Yet 1 is of type `Integer`, not `IntegerExpression`.
>> 
>> Currently all types of the standard library belong the program realm, not to the compiler realm. I wish we wouldn't break this practice, and avoid `RangeExpression`.
>> 
>> That's why I suggest `RangeProtocol`. Other options could be `Ranging`, `Bounds`...
>> 
>> Gwendal Roué
>> 
>> 
>> Le 19 avr. 2017 à 23:35, Jordan Rose <jordan_rose at apple.com <mailto:jordan_rose at apple.com>> a écrit :
>> 
>>> That was probably about the ObjC importer, which does this (appends "Protocol") when there's a class and protocol with the same name in the same module. That doesn't necessarily mean it's the right thing to put in the API guidelines, though.
>>> 
>>> Jordan
>>> 
>>> 
>>>> On Apr 19, 2017, at 10:59, Gmail via swift-evolution <swift-evolution at swift.org <mailto:swift-evolution at swift.org>> wrote:
>>>> 
>>>> I seem to recall that something (maybe a WWDC session) mentioned something about protocols that in essence represent a single type would have the Protocol-suffix. 
>>>> 
>>>> Unfortunately I couldn’t find it (yet?). The closest I’ve found so far is http://asciiwwdc.com/2014/sessions/407 <http://asciiwwdc.com/2014/sessions/407> but I’m not sure that was it.
>>>> > essentially when there's a conflict between a class name and a protocol name, we'll append protocol to the name of the protocol.
>>>> 
>>>> David
>>>> 
>>>>> On 19 Apr 2017, at 17:55, Gwendal Roué via swift-evolution <swift-evolution at swift.org <mailto:swift-evolution at swift.org>> wrote:
>>>>> 
>>>>> 
>>>>>> Le 19 avr. 2017 à 17:23, Gwendal Roué <gwendal.roue at gmail.com <mailto:gwendal.roue at gmail.com>> a écrit :
>>>>>> 
>>>>>> Re: [swift-evolution] [Review] SE-0172: One-sided Ranges
>>>>>> 
>>>>>> "RangeExpression" is an unexpected name. I was expecting "RangeProtocol", as in IteratorProtocol and LazySequenceProtocol. We need a consistent suffix for protocols that can't be named in -able,  -ible, or named with a simple noun because the noun is already used by a concrete type. "-Protocol" should be that prefix: RangeProtocol.
>>>>> 
>>>>> A detailed look at API Design Guidelines [1] shows that this subject is not addressed:
>>>>> 
>>>>>> 	• Protocols that describe what something is should read as nouns (e.g. `Collection`).
>>>>>> 	• Protocols that describe a capability should be named using the suffixes `able`, `ible`, or `ing` (e.g. `Equatable`, `ProgressReporting`).
>>>>> 
>>>>> Nothing is said for "protocols that describe what something but can't be named as nouns", or "protocols that describe a capability but can't be named using the suffixes able, ible, or ing".
>>>>> 
>>>>> For example: the name of the protocol for all ranges discussed with SE-0172 should be addressed by the first rule (because the protocol describes what something is rather than a capability). But that protocol can't be named Range because Range is already taken.
>>>>> 
>>>>> Such a situation comes rather easily:
>>>>> 
>>>>> - in an evolving code base, when a protocol is added on top of an existing type hierarchy which should be preserved (RangeProtocol added on top of Range, ClosedRange, etc.)
>>>>> - at the birth of a code base, when a protocol coexists with a concrete type which rightfully deserves the noun claimed by the protocol.
>>>>> 
>>>>> IteratorProtocol and LazySequenceProtocol have set a precedent: maybe we should have the API Design Guidelines evolve with a third rule:
>>>>> 
>>>>> + When a protocol can't be named with a noun, or with an `able`, `ible`, or `ing` suffix, the protocol should be named using the suffix `Protocol` (e.g. `IteratorProtocol`).
>>>>> 
>>>>> What do you think?
>>>>> 
>>>>> Gwendal Roué
>>>>> [1] https://swift.org/documentation/api-design-guidelines/ <https://swift.org/documentation/api-design-guidelines/>
>>>>> 
>>>>> _______________________________________________
>>>>> swift-evolution mailing list
>>>>> swift-evolution at swift.org <mailto:swift-evolution at swift.org>
>>>>> https://lists.swift.org/mailman/listinfo/swift-evolution <https://lists.swift.org/mailman/listinfo/swift-evolution>
>>>> 
>>>> _______________________________________________
>>>> swift-evolution mailing list
>>>> swift-evolution at swift.org <mailto:swift-evolution at swift.org>
>>>> https://lists.swift.org/mailman/listinfo/swift-evolution <https://lists.swift.org/mailman/listinfo/swift-evolution>
>>> 
> 

-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20170420/81bc0788/attachment.html>