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

[Dave Abrahams]

on Thu Jan 28 2016, Erica Sadun <swift-evolution at swift.org> wrote:

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

Seems like you *do* know; you jumped :-)

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

This description misses (or at least fails to emphasize) an aspect I
consider extremely important: protocols are not just bags of syntax.
It's crucial that they have well-defined, testable semantics.

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

As part of following the new guidelines, the proposal is that the
standard library drops the "Type" suffix altogether.

> 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
>
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution

-- 
-Dave