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

[Erica Sadun]

This is very cute but limited in terms of application. Recall that there are several members that can be described in protocols, not just method members, such as initializers, subscripts, etc. This is a nice rule to have in a personal style guide, but I think it's far too narrow for Apple-sourced guidance.

-- E

> On Jan 28, 2016, at 9:33 PM, Howard Lovatt <howard.lovatt at gmail.com> wrote:
> 
> For protocols named XXXble I think they should have a main method named XXX. If this were adopted then many protocol names would change, e.g.:
> 
>     1. ForwardIndexType would be Advanceable because it has advance methods and method successor() would be renamed advance().
>     2. Indexable would be Subscriptable because it has a subscript method.
>     3. Etc.
> 
> On 29 January 2016 at 05:03, Erica Sadun via swift-evolution <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 <mailto:swift-evolution at swift.org>> wrote:
>> 
>> 
>> on Wed Jan 27 2016, Dave <swift-evolution at swift.org <mailto: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
> 
> 
> 
> _______________________________________________
> 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>
> 
> 
> 
> 
> -- 
>   -- Howard.

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