[swift-evolution] [Review] SE-0006 Apply API Guidelines to the Standard Library

[Erica Sadun]

> On Jan 27, 2016, at 11:42 PM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 
> on Wed Jan 27 2016, Dave <swift-evolution at swift.org> wrote:
> 
>> Huh… Yeah, you’re right. I guess I saw “CollectionType” and
>> “CustomStringConvertible” or something and made a connection that
>> wasn’t there.
>> Well, FWIW, that convention (plus the occasional “HasNoun”, and
>> -ableType for constraining the element of custom collections) tends to
>> work well for me.
>> 
>> What’s been the deciding factor between -Type and -able so far?
> 
> When there's no reasonable -able or -ible name, use -Type.

This is where I never know whether to keep my nose out of things or just jump in. I find there are generally two kinds of protocols: verby-ones ("this is how this thing works") and nouny-ones ("this is what this thing is"). Here's the guidance I've been giving:

Swift protocols describe the surface that connect a feature provider API with its consumer. Protocols establish a communication contract. They ensure a fit between each required member and the provider’s implementation. It’s like whether a virus can attach to a host cell’s receptors, or whatever the actual biological equivalent is. The standard library describes protocols using nouns (typically ending in Type, e.g. MirrorPathType, MutableCollectionType, ErrorType) and adjectives (typically ending in ble, like Streamable, Strideable, ArrayLiteralConvertible). The former more commonly discuss what a conforming type is and the latter what it does.  

When naming a protocol, you’re not limited to Type and ble endings. Your protocol can be, for example, a DataProvider or a FloatConsumer. A protocol can describe a relationship DownloadProcessingDelegate or ListViewDataSource. You may implement an OutputDestination or an IntegerSink. The current API Design guidelines say "omit needless words", so you might prefer to go with DataProvider over DataProviderType or  MirrorPath over MirrorPathType, but I wouldn't give much more constraint to naming beyond that.

For example, for "HasNoun", I'd go with something more like NounContainingType or NounSupplier.

Non-Abrahams Dave writes: "I like -Type for protocols that can only be used a generic constraint, and -able/-ible for protocols that can be “concrete” types.

And Canonical Dave replies: "But that's not how they're used.  I'd have to rename Equatable and Comparable to follow that convention."

I agree in that I'm not convinced it's the role of a protocol to describe implementation details. (I'd say the same for method names, but that's different thread about mutability and side effects, etc). Going that way leads you to over-designated hungarian-esque guidelines that I'd rather keep loose, friendly, and sensible.

-- Erica


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