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

Gwendal Roué gwendal.roue at gmail.com
Wed Apr 19 10:55:58 CDT 2017


> Le 19 avr. 2017 à 17:23, Gwendal Roué <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/



More information about the swift-evolution mailing list