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

[Chris_Lattner]

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:

  swift-evolution/0041-conversion-protocol-conventions.md at master · apple/swift-evolution · GitHub

Reviews are an important part of the Swift evolution process. All reviews should be sent to the swift-evolution mailing list at

  https://lists.swift.org/mailman/listinfo/swift-evolution

or, if you would like to keep your feedback private, directly to the review manager.

What goes into a review?

The goal of the review process is to improve the proposal under review through constructive criticism and contribute to the direction of Swift. When writing your review, here are some questions you might want to answer in your review:

  * What is your evaluation of the proposal?
  * Is the problem being addressed significant enough to warrant a change to Swift?
  * Does this proposal fit well with the feel and direction of Swift?
  * If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?
  * How much effort did you put into your review? A glance, a quick reading, or an in-depth study?

More information about the Swift evolution process is available at

  swift-evolution/process.md at master · apple/swift-evolution · GitHub

Thank you,

-Chris Lattner
Review Manager

[Chris_Lattner]

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.

···

On May 10, 2016, at 11:48 AM, Chris Lattner <clattner@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

[Jed_Lewison]

I agree that CustomStringConvertible and CustomDebugStringConvertible are confusing, but in general, ‘Convertible’ and ‘Representable’ as currently used actually make sense to me.

Convert means to transform, so it feels natural to me to think of something that is a FooLiteralConvertible as being something that be converted from a FooLiteral.

To represent means to stand in for, so it feels natural to say that if a can represent b and b can represent a, then it’s representable.

The rub comes with CustomStringConvertible and CustomDebugStringConvertible, which while it makes sense linguistically, creates confusion in Swift because it converts in the opposite direction of all the other convertible protocols.

I’m not sure what the rationale was for moving away from Printable and DebugPrintable; maybe it was that everything should be printable? If so, then perhaps CustomPrintable and CustomDebugPrintable would do the job?

···

On May 10, 2016, at 11:48 AM, Chris Lattner via swift-evolution <swift-evolution@swift.org> 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

Reviews are an important part of the Swift evolution process. All reviews should be sent to the swift-evolution mailing list at

  https://lists.swift.org/mailman/listinfo/swift-evolution

or, if you would like to keep your feedback private, directly to the review manager.

What goes into a review?

The goal of the review process is to improve the proposal under review through constructive criticism and contribute to the direction of Swift. When writing your review, here are some questions you might want to answer in your review:

  * What is your evaluation of the proposal?
  * Is the problem being addressed significant enough to warrant a change to Swift?
  * Does this proposal fit well with the feel and direction of Swift?
  * If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?
  * How much effort did you put into your review? A glance, a quick reading, or an in-depth study?

More information about the Swift evolution process is available at

  https://github.com/apple/swift-evolution/blob/master/process.md

Thank you,

-Chris Lattner
Review Manager
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

[dwaite (David Waite)]

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

  * What is your evaluation of the proposal?

-1.

I’m not 100% sure on the names (can we paint the bike shed plaid?) but more importantly, I’m not sure the groupings are adequate

RawRepresentable seems to represent a sub-type declaring a super type coercion system.

The various literal-based initializers are not necessarily coercion operators - some operations (e.g. initializing a Set from a literal with repeating elements) are lossy. These initializers also are not given a mechanism to recover from failure (possibly because the literals mean that failure represents a precondition failure in the written code?). That would imply that these literal-based initializers are special - a non-literal needs failure-reporting semantics.

CustomStringRepresentable is not meant for any sort of type conversion. It returns a user presentation of the object as text (while the Debug variant is meant to return a developer presentation)

So I don’t feel these represent In, Out, and InOut but instead three different classifications of conversions.

  * Is the problem being addressed significant enough to warrant a change to Swift?

Now is a great time for naming consistency

  * Does this proposal fit well with the feel and direction of Swift?

Future direction there may be another change if coercion is defined as a language feature (such as implicit numeric coercion)

  * If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?

I thought of Ruby and the difference between to_s and to_str. The idea of a representation as a type vs coercion to a type is a hard one to learn.

  * How much effort did you put into your review? A glance, a quick reading, or an in-depth study?

A quick reading.

-DW

[hartbit (David Hart)]

  * What is your evaluation of the proposal?

+1 for the idea of making the naming consistent
-1 for the actual chosen names

Even after reading the reasoning behind the choice of those words, it took me a time to scratch my head around it. It’s definitely not immediately obvious that Convertible is bi-directional.

I would have preferred something much more obvious (even if less grammatically correct):

-InputProtocol
-OutputProtocol
-InputOutputProtocol or BidirectionalProtocol

Or:

-Inputable
-Outputable (got that from Haskell)
-InputOutputable or -Bidirectionalable

  * Is the problem being addressed significant enough to warrant a change to Swift?

Yes.

  * Does this proposal fit well with the feel and direction of Swift?

Yes for the idea of making them consistent, no for the names.

  * If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?

Haskell uses Outputable.

  * How much effort did you put into your review? A glance, a quick reading, or an in-depth study?

Read the proposal several times.

[Daniel_Steinberg]

+1 for the classification of the protocols to be renamed

I completely agree that you can divide the protocols being examined into those categories and I appreciate the effort put in to doing so.

-1 for the names chosen

···

======

The new Representable is being applied to -

CustomStringConvertible and CustomDebugStringConvertible.

I wouldn’t be upset with calling these StringRepresentable and DebugStringRepresentable but I would argue that these are very specific protocols whose purpose is to create strings that can be used while debugging and while printing. We are not converting. We could argue that we're representing, but I would say we are using these protocols to describe an object. I would suggest naming them

Describable and DebugDescribable

The downside is that this isn’t extensible to other protocols that are creating instances but that isn’t really what’s being done here. These two are specific use cases.

=====

The current RawRepresentable does, in my opinion, completely describe what it represents. Calling it Convertible is not, in my opinion, appropriate.

The authors argue that it’s a preferred name because Convertible operates in both directions, but that isn’t the case with RawRepresentable. I can always ask a RawRepresentable instance for its rawValue but I will not always be able to successfully create a RawRepresentable instance from an arbitrary rawValue even if it is of the appropriate type. In fact, I think that their definition of Representable supports keeping RawRepresentable named as it is.

RawRepresentable says to me that an instance can be represented by a rawValue of a specified type. We are not guaranteed that we can create an instance from this type.

======

Given the above two comments, there is no longer any confusion with the remaining types that are currently labeled Convertible that are in the proposed Creatable category. I don’t know that Convertible is the right word - Creatable might be better - but there doesn’t seem to be enough of a reason to change the existing name. I wouldn’t be upset with keeping these as Convertible or changing them to Creatable.

======

I’ve been thinking about these a lot. Last fall Greg Heo gave a great presentation about how to group the standard library protocols according to their names. The two that stick out for me are CustomStringConvertible and CustomDebugStringConvertible. One reason they stick out is the prefix “Custom”. The other is that we aren’t converting something - we are describing or representing.

Daniel

On May 10, 2016, at 2:48 PM, Chris Lattner via swift-evolution <swift-evolution@swift.org> 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

Reviews are an important part of the Swift evolution process. All reviews should be sent to the swift-evolution mailing list at

  https://lists.swift.org/mailman/listinfo/swift-evolution

or, if you would like to keep your feedback private, directly to the review manager.

What goes into a review?

The goal of the review process is to improve the proposal under review through constructive criticism and contribute to the direction of Swift. When writing your review, here are some questions you might want to answer in your review:

  * What is your evaluation of the proposal?
  * Is the problem being addressed significant enough to warrant a change to Swift?
  * Does this proposal fit well with the feel and direction of Swift?
  * If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?
  * How much effort did you put into your review? A glance, a quick reading, or an in-depth study?

More information about the Swift evolution process is available at

  https://github.com/apple/swift-evolution/blob/master/process.md

Thank you,

-Chris Lattner
Review Manager
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

[benrimmington]

Re: UPDATED APPROACH
<http://thread.gmane.org/gmane.comp.lang.swift.evolution/16619/focus=17089&gt;

## Initializable

+1 although the existing -Convertible suffix isn't bad.

(ExtendedGraphemeClusterLiteral could also be renamed to CharacterLiteral).

## Representable

+1 for the Custom[Debug]StringRepresentable protocols.

(The related Streamable and OutputStream[able] names are also problematic).

-- Ben

[Brad_Hilton]

* What is your evaluation of the proposal?

+1. Having consistent conventions makes sense to me. I’d prefer `Initializable` to `Creatable` which sounds weird to me, but otherwise sounds great.

* Is the problem being addressed significant enough to warrant a change to Swift?

I think semantic consistency is important.

* Does this proposal fit well with the feel and direction of Swift?

Yes.

* If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?

I don’t know if I’ve seen a similar standard in other languages.

* How much effort did you put into your review? A glance, a quick reading, or an in-depth study?

I’ve been following this proposal for weeks and if approved it will influence my work.

···

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

Reviews are an important part of the Swift evolution process. All reviews should be sent to the swift-evolution mailing list at

https://lists.swift.org/mailman/listinfo/swift-evolution

or, if you would like to keep your feedback private, directly to the review manager.

What goes into a review?

The goal of the review process is to improve the proposal under review through constructive criticism and contribute to the direction of Swift. When writing your review, here are some questions you might want to answer in your review:

* What is your evaluation of the proposal?
* Is the problem being addressed significant enough to warrant a change to Swift?
* Does this proposal fit well with the feel and direction of Swift?
* If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?
* How much effort did you put into your review? A glance, a quick reading, or an in-depth study?

More information about the Swift evolution process is available at

https://github.com/apple/swift-evolution/blob/master/process.md

Thank you,

-Chris Lattner
Review Manager

[Tony_Allevato]

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

Reviews are an important part of the Swift evolution process. All reviews
should be sent to the swift-evolution mailing list at

        https://lists.swift.org/mailman/listinfo/swift-evolution

or, if you would like to keep your feedback private, directly to the
review manager.

What goes into a review?

The goal of the review process is to improve the proposal under review
through constructive criticism and contribute to the direction of Swift.
When writing your review, here are some questions you might want to answer
in your review:

        * What is your evaluation of the proposal?

+1 with the newly proposed Initializable/Representable names. Initializable
just fits perfectly with the fact that Swift has things called initializers
and is a vast improvement over Creatable. Representable to denote the other
direction makes sense compared to existing Cocoa APIs that use
*Representation in their name.

        * Is the problem being addressed significant enough to warrant a
change to Swift?

Yes. Many developers use stdlib as guidance when designing their own APIs
and having the standard library be internally consistent sets a good
example. These recommendations should also be hoisted into the API naming
guidelines documentation so that people can easily cite it, as opposed to
just saying "note the pattern that exists" (this is helpful when writing
team-specific style guides and for enforcing conventions in code reviews).

        * Does this proposal fit well with the feel and direction of Swift?

Yes, it makes the language more consistent.

        * If you have used other languages or libraries with a similar
feature, how do you feel that this proposal compares to those?

None that handle conversions in this way using protocols.

        * How much effort did you put into your review? A glance, a quick
reading, or an in-depth study?

I read the proposal, the message with the updated names afterwards, and
loosely followed the e-mail threads.

···

On Tue, May 10, 2016 at 11:48 AM Chris Lattner via swift-evolution < swift-evolution@swift.org> wrote:

More information about the Swift evolution process is available at

        https://github.com/apple/swift-evolution/blob/master/process.md

Thank you,

-Chris Lattner
Review Manager
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

[Matthew_Johnson]

   * What is your evaluation of the proposal?

+1 for the idea of making the naming consistent
-1 for the actual chosen names

Even after reading the reasoning behind the choice of those words, it took me a time to scratch my head around it. It’s definitely not immediately obvious that Convertible is bi-directional.

I would have preferred something much more obvious (even if less grammatically correct):

-InputProtocol
-OutputProtocol
-InputOutputProtocol or BidirectionalProtocol

Or:

-Inputable
-Outputable (got that from Haskell)
-InputOutputable or -Bidirectionalable

Thanks for your feedback.

To be honest, I'm not a fan of the names you suggest. Erica had a similar variation using To, From, and ToAndFrom prefixes that I find preferable to your suggestions if we were to go in this direction. That said, I think the names in our proposal feel more Swifty.

···

Sent from my iPad
On May 10, 2016, at 5:56 PM, David Hart via swift-evolution <swift-evolution@swift.org> wrote:

   * Is the problem being addressed significant enough to warrant a change to Swift?

Yes.

   * Does this proposal fit well with the feel and direction of Swift?

Yes for the idea of making them consistent, no for the names.

   * If you have used other languages or libraries with a similar feature, how do you feel that this proposal compares to those?

Haskell uses Outputable.

   * How much effort did you put into your review? A glance, a quick reading, or an in-depth study?

Read the proposal several times.
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

[Erica_Sadun]

We'd be happy to bikeshed again.

I think fundamentally our take on this is:

* We want there to be a standard that expresses the three conversion/initialization styles.
* We feel the system is currently broken. And we want to have a coherent and settled vision in place for 3, even imperfect.
* We're flexible about the naming but it should be (1) Swifty and (2) well grounded in meaning.

Let me turn the floor over to Matthew here.

-- E

···

On May 10, 2016, at 6:51 PM, Chris Lattner via swift-evolution <swift-evolution@swift.org> wrote:

On May 10, 2016, at 11:48 AM, Chris Lattner <clattner@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:

[hartbit (David Hart)]

I don’t think that my suggestions should be taken literally, more as an example that I would prefer a much more straight forward naming scheme, to improve discoverability, even if it is at the expense of more “swift” names.

···

On 11 May 2016, at 01:02, Matthew Johnson <musical.matthew@mac.com> wrote:

Thanks for your feedback.

To be honest, I'm not a fan of the names you suggest. Erica had a similar variation using To, From, and ToAndFrom prefixes that I find preferable to your suggestions if we were to go in this direction. That said, I think the names in our proposal feel more Swifty.

[anandabits (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@swift.org> wrote:

On May 10, 2016, at 11:48 AM, Chris Lattner <clattner@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@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

[griotspeak (TJ Usiyan)]

I've been thinking about the "conversion to some other type from this
protocol" case for a while since it often seems to go against the guidance
to add a property for this conversion. `Convertible` is always an awkward
Protocol to write, in my opinion.

Is there a chance that we simplify the the `Convertible` case by adding
this syntax to protocols

protocol CustomStringConvertible {
    String.init(customStringFrom:)
}

or something similar? I admit that it *is* unwieldy to declare that String
has an initializer in a protocol *but* we almost always end up writing an
initializer which accepts our protocol and calls the 'constructor property'
we've required in the protocol. This removes that indirection (also
removing the strange two-ways-in-our-API-to-convert-this-to-that) and,
maybe, avoids some overloading.

···

On Mon, May 16, 2016 at 10:33 AM, Tony Allevato via swift-evolution < swift-evolution@swift.org> wrote:

On Tue, May 10, 2016 at 11:48 AM Chris Lattner via swift-evolution < > swift-evolution@swift.org> 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

Reviews are an important part of the Swift evolution process. All reviews
should be sent to the swift-evolution mailing list at

        https://lists.swift.org/mailman/listinfo/swift-evolution

or, if you would like to keep your feedback private, directly to the
review manager.

What goes into a review?

The goal of the review process is to improve the proposal under review
through constructive criticism and contribute to the direction of Swift.
When writing your review, here are some questions you might want to answer
in your review:

        * What is your evaluation of the proposal?

+1 with the newly proposed Initializable/Representable names.
Initializable just fits perfectly with the fact that Swift has things
called initializers and is a vast improvement over Creatable. Representable
to denote the other direction makes sense compared to existing Cocoa APIs
that use *Representation in their name.

        * Is the problem being addressed significant enough to warrant a
change to Swift?

Yes. Many developers use stdlib as guidance when designing their own APIs
and having the standard library be internally consistent sets a good
example. These recommendations should also be hoisted into the API naming
guidelines documentation so that people can easily cite it, as opposed to
just saying "note the pattern that exists" (this is helpful when writing
team-specific style guides and for enforcing conventions in code reviews).

        * Does this proposal fit well with the feel and direction of
Swift?

Yes, it makes the language more consistent.

        * If you have used other languages or libraries with a similar
feature, how do you feel that this proposal compares to those?

None that handle conversions in this way using protocols.

        * How much effort did you put into your review? A glance, a quick
reading, or an in-depth study?

I read the proposal, the message with the updated names afterwards, and
loosely followed the e-mail threads.

More information about the Swift evolution process is available at

        https://github.com/apple/swift-evolution/blob/master/process.md

Thank you,

-Chris Lattner
Review Manager
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

[xwu (Xiaodi Wu)]

Like David Hart and the anonymous reviewer, I agree that the problem is
worth solving but the proposed names leave something to be desired. I'd
like to offer a minimalist suggestion:

Initializable -- for what's currently "LiteralConvertible" (and also
StringInterpolationConvertible)
Convertible -- for "StringConvertible" protocols
Representable -- keep as it is currently

I agree with others that "Creatable" is a strange term because it's not
used anywhere else. Looking at the auto-generated docs for the
"LiteralConvertible" protocols, it says that conforming types "can be
initialized with" whatever thing is said to be convertible. I think that
offers a pretty clear alternative word--namely, "initializable."

I can live with "convertible" being one-way. Not all "convertible" things
are like convertible cars. When you convert from one faith to another, for
example, some level of finality is intended.

I can also live with the current usage of the term "representable." In the
context of things like "representable values" in floating point types,
representability suggests exactness and thus round-trippability.

(And to use the example in the proposal, a lawyer who represents you well
[*] is one that communicates your position to the court. You "input" your
position, your lawyer goes to court, and then they "output" your position
in legalese to the court. If there's degradation in the quality of the
"output," then you've been inadequately represented.)

[*And, it bears clarifying that your lawyer is considered to represent
*you* and not merely *your interests*. If you're the plaintiff in a case
and your lawyers says, "My client's entitled to a million dollars!", the
court can restate that as "Plaintiff argues that she's entitled to a
million dollars."]

···

On Tue, May 10, 2016 at 9:33 PM, Erica Sadun via swift-evolution < swift-evolution@swift.org> wrote:

> On May 10, 2016, at 6:51 PM, Chris Lattner via swift-evolution < > swift-evolution@swift.org> wrote:
>
>
>> On May 10, 2016, at 11:48 AM, Chris Lattner <clattner@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:

We'd be happy to bikeshed again.

I think fundamentally our take on this is:

* We want there to be a standard that expresses the three
conversion/initialization styles.
* We feel the system is currently broken. And we want to have a coherent
and settled vision in place for 3, even imperfect.
* We're flexible about the naming but it should be (1) Swifty and (2) well
grounded in meaning.

Let me turn the floor over to Matthew here.

[anandabits (Matthew Johnson)]

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:

We'd be happy to bikeshed again.

I think fundamentally our take on this is:

* We want there to be a standard that expresses the three conversion/initialization styles.
* We feel the system is currently broken. And we want to have a coherent and settled vision in place for 3, even imperfect.
* We're flexible about the naming but it should be (1) Swifty and (2) well grounded in meaning.

Let me turn the floor over to Matthew here.

I agree with Erica here.

There was a significant round of bike shedding that went into this proposal a few months ago, but there is no harm in continuing that exercise now that a broader audience is engaged. As many reviewers have agreed, the important thing is to settle on *something*.

Several reviewers have mentioned Creatable as not feeling Swifty. FWIW, the history behind the name is that we wanted something that will work regardless of the mechanism. It should be a sensible name whether the requirement is an initializer or a factory method.

I'm hoping we can reach a convention that most of us are happy with by the end of the review period.

···

Sent from my iPad

On May 10, 2016, at 9:33 PM, Erica Sadun <erica@ericasadun.com> wrote:

On May 10, 2016, at 6:51 PM, Chris Lattner via swift-evolution <swift-evolution@swift.org> wrote:

On May 10, 2016, at 11:48 AM, Chris Lattner <clattner@apple.com> wrote:

-- E

[Patrick_Smith]

How about:

Consuming (from)
Producing (to)

IntegerLiteralConsuming
StringLiteralConsuming

CustomStringProducing
CustomDebugStringProducing

As for something that does both, all I could find was ‘bidirectional’, ‘two-way’, ‘mutual’, ‘duplex’. I tried searching in biology (https://en.wikipedia.org/wiki/Organic_reaction\), but couldn’t find anything. I like the idea of just conforming to both protocols, and some sort of protocol typealias. Or staying with Representable.

···

On 11 May 2016, at 12:33 PM, Erica Sadun via swift-evolution <swift-evolution@swift.org> wrote:

On May 10, 2016, at 6:51 PM, Chris Lattner via swift-evolution <swift-evolution@swift.org> wrote:

On May 10, 2016, at 11:48 AM, Chris Lattner <clattner@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:

We'd be happy to bikeshed again.

I think fundamentally our take on this is:

* We want there to be a standard that expresses the three conversion/initialization styles.
* We feel the system is currently broken. And we want to have a coherent and settled vision in place for 3, even imperfect.
* We're flexible about the naming but it should be (1) Swifty and (2) well grounded in meaning.

Let me turn the floor over to Matthew here.

-- E

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

[pyrtsa (Pyry Jahkola)]

Taking the suggested changes into account, here's my review.

1) +1, I think this is a reasonable way for naming this family of protocols.

2) The problem isn't huge, but I think it's worth fixing. So far, the naming of stdlib protocols has been somewhat inconsistent in this regard.

3) I've used other languages & stdlibs with similar naming schemes, although none of them used the words "initializable" and "representable". Common alternatives have been word compositions involving expressions such as "convertible", "from", "to", "bi(jective)", "can build". However, I think "init" is so central in Swift that the use of "Initializable" is well justified. "Representable" is slightly less so but self-explanatory IMO, and more so than "convertible" which could be understood either or both ways.

4) Quick reading.

— Pyry

···

On 13 May 2016, Matthew Johnson wrote:

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

[Daniel_Steinberg]

I appreciate your rework on this - I still don’t understand one thing and disagree with a second:

(1) I don’t understand what the word “Custom” adds to CustomStringRepresentable and CustomDebugStringRepresentable and would drop that prefix (even if it remains Convertible).

(2) The use case for these two still stands out from every other protocol on the list. The intent is (was) better captured by “Describable”. i.e. these are things for which there is a description. I think it is more descriptive to name them Describable and DebugDescribable.

Best,

Daniel

···

On May 13, 2016, at 12:31 PM, Matthew Johnson via swift-evolution <swift-evolution@swift.org> wrote:

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@swift.org <mailto:swift-evolution@swift.org>> wrote:

On May 10, 2016, at 11:48 AM, Chris Lattner <clattner@apple.com <mailto:clattner@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@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution

[Daniel_Steinberg]

I like this much better but would recommend the word “Custom” be dropped from StringRepresentable and DebugS

···

On May 13, 2016, at 12:31 PM, Matthew Johnson via swift-evolution <swift-evolution@swift.org> wrote:

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@swift.org <mailto:swift-evolution@swift.org>> wrote:

On May 10, 2016, at 11:48 AM, Chris Lattner <clattner@apple.com <mailto:clattner@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@swift.org <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution

_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution