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

[Dave Abrahams]

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

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

+1

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

-- 
-Dave