[swift-evolution] [swift-evolution-announce] [Review] SE-0041: Updating Protocol Naming Conventions for Conversions

[Matthew Johnson]

While the community feedback on our SE-0041 proposal "Updating Protocol Naming Conventions for Conversions" (https://github.com/apple/swift-evolution/blob/master/proposals/0041-conversion-protocol-conventions.md) has been positive about the need to establish conventions, feedback has been mixed to negative with regard to the specific conventions suggested in the proposal.

With that in mind, Erica and I have been working on refactoring those recommendations. We put together the following update and invite the community to bikeshed further with us. We hope this offers the Swift core team the flexibility to accept our proposal "with revision" if an alternative garners more support. With luck, we'll reach a naming consensus during the review period.

UPDATED APPROACH

Our updated approach focuses on the two most important conventions: one for initialization and one for representation.

1. `Initializable`

`Initializable` designates protocols that convert *from* a type or from an associated type mentioned in the protocol name, such as the current `<Type>LiteralConvertible` protocols.  This convention would include member requirements for initializers, factory methods, and any other way an instance can be imported to establish a new instance of the conforming type.

For example, conforming to `ArrayLiteralInitializable` would allow a set to be created with `Set(arrayLiteral: <some array>)` and `var set: Set<T> = []`.

This phrase replaces the `Creatable` form from our original proposal.

2. `Representable`

`Representable` designates protocols whose primary purpose is to project *to* a type or associated type mentioned in the protocol name.  Items in the standard library that would be subsumed into this naming include `CustomStringConvertible`, `CustomDebugStringConvertible`, and `RawRepresentable`, which we imagine would become `CustomStringRepresentable`, `CustomDebugStringRepresentable`, and (as current) `RawRepresentable`.

This second category groups together the `Convertible` and `Representable` categories from our original proposal and is predicated on the feedback from the design team review. The `Representable` designation does not promise bidirectional conversion although some `Representable` protocols may include requirements to allow attempted initialization *from* the type of the representation. Doing so falls outside the naming contract we are proposing. 

FUTURE DIRECTIONS

We did not include a third category for bidirectional conversion in this update. We recognize that style of contract is rare in Swift. Lossless conversion does not appear in the standard library outside of `RawRepresentable`, which we agreed was better covered by `Representable`. If such a convention is needed or adopted, we reserve the `Isomorphic` designation for future use.

Sent from my iPad

> On May 10, 2016, at 7:51 PM, Chris Lattner via swift-evolution <swift-evolution at swift.org> wrote:
> 
> 
>> On May 10, 2016, at 11:48 AM, Chris Lattner <clattner at apple.com> wrote:
>> 
>> Hello Swift community,
>> 
>> The review of "SE-0041: Updating Protocol Naming Conventions for Conversions" begins now and runs through May 16. The proposal is available here:
>> 
>>    https://github.com/apple/swift-evolution/blob/master/proposals/0041-conversion-protocol-conventions.md
> 
> Here are comments from someone who preferred to stay anonymous.  These are not my own:
> 
> 
> 
> 
> * What is your evaluation of the proposal?
> 
> I rather agree with the comments mentioned in the proposal from the Standard Library design team, in that I agree with the basic intention of the proposal, but I’m not convinced about the proposed answer. Specifically:
> 
> 1) I agree with the proposal that Representable seems more suited to meaning “a representation can be created from this type”. This is in line with existing Cocoa APIs that use “dictionaryRepresentation” to generate a dictionary that represents the object (for e.g. serialization to JSON). See, for example, NSUbiquitousKeyValueStore, NSUserDefaults, and SCNTechnique. Out of those, only the last one can also be initialized from a dictionary, so the term “representation” as used in existing Cocoa frameworks seems better suited for implying only a one-way conversion (and also feels natural to me).
> 
> 2) I’m not convinced on Creatable. I’ve been using Convertible for protocols that imply that the type can be initialized from another type (e.g. the DictionaryConvertible protocol would contain init(dictionary:), and thus SCNTechnique would conform to it). This also seems in line with the bulk of the “Convertible” protocols in the standard library today. The word “creatable" strikes me as strange, because the term “create” isn’t used anywhere else in regards to initialization that I know of.
> 
> 3) I’m not positive that we need a third protocol that implies bidirectionality. I’m not opposed to it, but if raw values conformed to both RawConvertible and RawRepresentable to indicate both their initialization and generated representation qualities, I’d be fine with that. And then maybe there’s just a typealias for RawValueProtocol that combines those for convenience.
> 
> 
> * Is the problem being addressed significant enough to warrant a change to Swift?
> 
> Yes, in that I think it would be good to establish a clear convention here and stick to it. Whether the “Creatable” term is sufficiently clear to warrant a renaming of all the “Convertible” protocols, I’m not as sure about. I think at least CustomStringRepresentable and CustomDebugStringRepresentable would be worth doing since they imply a different direction from all the other “Convertible" protocols.
> 
> 
> * Does this proposal fit well with the feel and direction of Swift?
> 
> Yes, insofar as Swift generally seems to value predictability and consistency, and this would improve upon that.
> 
> 
> * If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?
> 
> The most relevant library here I think is the Cocoa libraries, as mentioned above, which are already using the term “representation” to mean a one-way conversion to another type.
> 
> 
> * How much effort did you put into your review? A glance, a quick reading, or an in-depth study?
> 
> I’ve been thinking about this for a while with regards to dictionary serialization, because it’s so common for data models, but I haven’t necessarily thought through all the implications for e.g. raw values.
> 
> _______________________________________________
> swift-evolution mailing list
> swift-evolution at swift.org
> https://lists.swift.org/mailman/listinfo/swift-evolution
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <https://lists.swift.org/pipermail/swift-evolution/attachments/20160513/2150ca8b/attachment.html>