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

[Erica Sadun]

> On Jan 29, 2016, at 9:29 AM, Dave Abrahams via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 
> on Thu Jan 28 2016, Erica Sadun <swift-evolution at swift.org <mailto: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.

Good point and I'll adjust my notes!

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

Fair enough.

So far we're still agreeing though.

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


This is the big bit though and you didn't respond here, although it's mostly that I'm agreeing with you but
what do you think about just cutting out things that get too specific? (I say the same more or less in the
longer review email)

>> 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
> 
> _______________________________________________
> 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/20160129/6f82a8e2/attachment.html>