renaming CustomStringConvertible


(Eric Habberstad) #1

To the Swift community,

May I put forth a couple of new names for the following protocol:

- CustomStringConvertible — rename as ‘Descriptive’ or as ‘Revealable’

Two goals for Swift is clarity and joy in use of the language, so I strongly feel that ‘Custom-‘ not be part of any new name here since it contributes little except verbosity, and ‘-String-‘ should be dropped too since ‘CustomStringConvertible’ has nothing to do with the String struct proper. The protocol only consists of the var description, after all.

Of course, the corollary would be ‘DebugDescriptive’ or ‘DebugRevealable’

I did consider ‘Describable’ as a name but to me ‘Descriptive’ looks and sounds better and captures the essence of what CustomStringConvertible really is. ‘Revealable’ as an alternate sounds, pardon the pun, almost as descriptive and has a bit of a classier ring to it.

This is a followup, albeit partial, to the final review of proposal SE-0041 which noted that the community was quite positive about the stated need to rename this and some other protocols, but just needs agreement on new names.

— Eric


(Dmitri Gribenko) #2

Hi Eric,

This protocol was called Printable before, but it caused a lot of
confusion for developers, and was guiding the developers toward
writing incorrect APIs. We have seen a lot of developers writing code
like this:

func printAll(_ values: [Printable]) {
  for v in values { print(v) }
}

This code is unnecessarily restrictive since in Swift everything can
be converted into a String.

func printAll(_ values: [Any]) {
  for v in values { print(v) }
}

The same goes for retrieving debug descriptions and mirrors. Any
value can do that. It is just that some values can opt into
customizing this behavior.

Thus, we renamed the protocols, adding the Custom~ prefix. Our
intention was to encourage only conformances to these protocols, and
discourage writing APIs against them.

Dmitri

···

On Fri, Jul 1, 2016 at 12:16 PM, Eric Habberstad via swift-evolution <swift-evolution@swift.org> wrote:

To the Swift community,

May I put forth a couple of new names for the following protocol:

- CustomStringConvertible — rename as ‘Descriptive’ or as ‘Revealable’

Two goals for Swift is clarity and joy in use of the language, so I strongly
feel that ‘Custom-‘ not be part of any new name here since it contributes
little except verbosity

--
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr@gmail.com>*/


(Xiaodi Wu) #3

IIRC, "custom" was used because it's not just conforming types that are
string convertible; it's that these types have a custom string conversion.
I can appreciate how this is an important point to communicate.

···

On Fri, Jul 1, 2016 at 14:16 Eric Habberstad via swift-evolution < swift-evolution@swift.org> wrote:

To the Swift community,

May I put forth a couple of new names for the following protocol:

- CustomStringConvertible — rename as ‘Descriptive’ or as ‘Revealable’

Two goals for Swift is clarity and joy in use of the language, so I
strongly feel that ‘Custom-‘ not be part of any new name here since it
contributes little except verbosity, and ‘-String-‘ should be dropped too
since ‘CustomStringConvertible’ has nothing to do with the String struct
proper. The protocol only consists of the *var description*, after all.

Of course, the corollary would be ‘DebugDescriptive’ or ‘DebugRevealable’

I did consider ‘Describable’ as a name but to me ‘Descriptive’ looks and
sounds better and captures the essence of what CustomStringConvertible
really is. ‘Revealable’ as an alternate sounds, pardon the pun, almost as
descriptive and has a bit of a classier ring to it.

This is a followup, albeit partial, to the final review of proposal
SE-0041 which noted that the community was quite positive about the
stated need to rename this and some other protocols, but just needs
agreement on new names.

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


(Vladimir) #4

To the Swift community,

May I put forth a couple of new names for the following protocol:

- CustomStringConvertible — rename as ‘Descriptive’ or as ‘Revealable’

Strong +1 from me. It looks and reads nice, clearly shows the meaning of the protocol i.e. what it for : to describe the type. I.e. the conformed type could be described. Don't think we need `String` word here as it is IMO clearly that description is usually a text describing something.

···

On 01.07.2016 22:16, Eric Habberstad via swift-evolution wrote:

Two goals for Swift is clarity and joy in use of the language, so I
strongly feel that ‘Custom-‘ not be part of any new name here since it
contributes little except verbosity, and ‘-String-‘ should be dropped too
since ‘CustomStringConvertible’ has nothing to do with the String struct
proper. The protocol only consists of the *var description*, after all.

Of course, the corollary would be ‘DebugDescriptive’ or ‘DebugRevealable’

I did consider ‘Describable’ as a name but to me ‘Descriptive’ looks and
sounds better and captures the essence of what CustomStringConvertible
really is. ‘Revealable’ as an alternate sounds, pardon the pun, almost as
descriptive and has a bit of a classier ring to it.

This is a followup, albeit partial, to the final review of proposal SE-0041
which noted that the community was quite positive about the stated need to
rename this and some other protocols, but just needs agreement on new names.

— Eric

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


(Dave Abrahams) #5

In fact, this should be in the “frequently rejected” list.

···

on Fri Jul 01 2016, Dmitri Gribenko <swift-evolution@swift.org> wrote:

On Fri, Jul 1, 2016 at 12:16 PM, Eric Habberstad via swift-evolution > <swift-evolution@swift.org> wrote:

To the Swift community,

May I put forth a couple of new names for the following protocol:

- CustomStringConvertible — rename as ‘Descriptive’ or as ‘Revealable’

Two goals for Swift is clarity and joy in use of the language, so I strongly
feel that ‘Custom-‘ not be part of any new name here since it contributes
little except verbosity

Hi Eric,

This protocol was called Printable before, but it caused a lot of
confusion for developers, and was guiding the developers toward
writing incorrect APIs. We have seen a lot of developers writing code
like this:

func printAll(_ values: [Printable]) {
  for v in values { print(v) }
}

This code is unnecessarily restrictive since in Swift everything can
be converted into a String.

func printAll(_ values: [Any]) {
  for v in values { print(v) }
}

The same goes for retrieving debug descriptions and mirrors. Any
value can do that. It is just that some values can opt into
customizing this behavior.

Thus, we renamed the protocols, adding the Custom~ prefix. Our
intention was to encourage only conformances to these protocols, and
discourage writing APIs against them.

--
Dave


(Xiaodi Wu) #6

Perhaps another candidate for sinking into `Syntax`?

···

On Fri, Jul 1, 2016 at 14:23 Dmitri Gribenko via swift-evolution < swift-evolution@swift.org> wrote:

On Fri, Jul 1, 2016 at 12:16 PM, Eric Habberstad via swift-evolution > <swift-evolution@swift.org> wrote:
>
> To the Swift community,
>
> May I put forth a couple of new names for the following protocol:
>
>
> - CustomStringConvertible — rename as ‘Descriptive’ or as ‘Revealable’
>
>
> Two goals for Swift is clarity and joy in use of the language, so I
strongly
> feel that ‘Custom-‘ not be part of any new name here since it contributes
> little except verbosity

Hi Eric,

This protocol was called Printable before, but it caused a lot of
confusion for developers, and was guiding the developers toward
writing incorrect APIs. We have seen a lot of developers writing code
like this:

func printAll(_ values: [Printable]) {
  for v in values { print(v) }
}

This code is unnecessarily restrictive since in Swift everything can
be converted into a String.

func printAll(_ values: [Any]) {
  for v in values { print(v) }
}

The same goes for retrieving debug descriptions and mirrors. Any
value can do that. It is just that some values can opt into
customizing this behavior.

Thus, we renamed the protocols, adding the Custom~ prefix. Our
intention was to encourage only conformances to these protocols, and
discourage writing APIs against them.

Dmitri

--
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr@gmail.com>*/
_______________________________________________
swift-evolution mailing list
swift-evolution@swift.org
https://lists.swift.org/mailman/listinfo/swift-evolution


(Vladimir) #7

To the Swift community,

May I put forth a couple of new names for the following protocol:

- CustomStringConvertible — rename as ‘Descriptive’ or as ‘Revealable’

Two goals for Swift is clarity and joy in use of the language, so I strongly
feel that ‘Custom-‘ not be part of any new name here since it contributes
little except verbosity

Hi Eric,

This protocol was called Printable before, but it caused a lot of
confusion for developers, and was guiding the developers toward
writing incorrect APIs. We have seen a lot of developers writing code
like this:

func printAll(_ values: [Printable]) {
  for v in values { print(v) }
}

This code is unnecessarily restrictive since in Swift everything can
be converted into a String.

Yes, but IMO someone, who don't know this can still write

func printAll(_ values: [CustomStringConvertible]) {
   for v in values { print(v) }
}

So, I don't see how this name should help to understand that "everything can be converted into a String". This is a knowledge that one should read in docs, IMO.

For me it seems logical: "everything could be printed" + "but those who is Descriptive, will be printed by their .description property".

As for CustomStringConvertible, it seems like you need .asCustromString (or just .asString) property, not .description. This confuses. Or each "thing" should have .description/.asString, but one who needs can override it(to be "custom" representable).

Just some thoughts.

···

On 01.07.2016 22:22, Dmitri Gribenko via swift-evolution wrote:

On Fri, Jul 1, 2016 at 12:16 PM, Eric Habberstad via swift-evolution > <swift-evolution@swift.org> wrote:

func printAll(_ values: [Any]) {
  for v in values { print(v) }
}

The same goes for retrieving debug descriptions and mirrors. Any
value can do that. It is just that some values can opt into
customizing this behavior.

Thus, we renamed the protocols, adding the Custom~ prefix. Our
intention was to encourage only conformances to these protocols, and
discourage writing APIs against them.

Dmitri


(Dmitri Gribenko) #8

They can still write this code, the compiler will accept it. In
practice we found that changing the name helped and developers are now
much less likely to code APIs against CustomStringConvertible. The
old name, Printable, strongly implied a capability (like Equatable,
Comparable, Hashable). The new name does not suggest that
printability is a capability provided by this protocol.

Dmitri

···

On Fri, Jul 1, 2016 at 12:48 PM, Vladimir.S <svabox@gmail.com> wrote:

On 01.07.2016 22:22, Dmitri Gribenko via swift-evolution wrote:

On Fri, Jul 1, 2016 at 12:16 PM, Eric Habberstad via swift-evolution >> <swift-evolution@swift.org> wrote:

To the Swift community,

May I put forth a couple of new names for the following protocol:

- CustomStringConvertible — rename as ‘Descriptive’ or as ‘Revealable’

Two goals for Swift is clarity and joy in use of the language, so I
strongly
feel that ‘Custom-‘ not be part of any new name here since it contributes
little except verbosity

Hi Eric,

This protocol was called Printable before, but it caused a lot of
confusion for developers, and was guiding the developers toward
writing incorrect APIs. We have seen a lot of developers writing code
like this:

func printAll(_ values: [Printable]) {
  for v in values { print(v) }
}

This code is unnecessarily restrictive since in Swift everything can
be converted into a String.

Yes, but IMO someone, who don't know this can still write

func printAll(_ values: [CustomStringConvertible]) {
  for v in values { print(v) }
}

So, I don't see how this name should help to understand that "everything can
be converted into a String". This is a knowledge that one should read in
docs, IMO.

--
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr@gmail.com>*/


(David Sweeris) #9

Maybe... It's just a property, though. I think if something's moving into the Syntax thing, I'd rather look for a way to move string interpolation there. Maybe.

- Dave Sweeris

···

On Jul 1, 2016, at 14:24, Xiaodi Wu via swift-evolution <swift-evolution@swift.org> wrote:

Perhaps another candidate for sinking into `Syntax`?

On Fri, Jul 1, 2016 at 14:23 Dmitri Gribenko via swift-evolution <swift-evolution@swift.org> wrote:
On Fri, Jul 1, 2016 at 12:16 PM, Eric Habberstad via swift-evolution >> <swift-evolution@swift.org> wrote:
>
> To the Swift community,
>
> May I put forth a couple of new names for the following protocol:
>
>
> - CustomStringConvertible — rename as ‘Descriptive’ or as ‘Revealable’
>
>
> Two goals for Swift is clarity and joy in use of the language, so I strongly
> feel that ‘Custom-‘ not be part of any new name here since it contributes
> little except verbosity

Hi Eric,

This protocol was called Printable before, but it caused a lot of
confusion for developers, and was guiding the developers toward
writing incorrect APIs. We have seen a lot of developers writing code
like this:

func printAll(_ values: [Printable]) {
  for v in values { print(v) }
}

This code is unnecessarily restrictive since in Swift everything can
be converted into a String.

func printAll(_ values: [Any]) {
  for v in values { print(v) }
}

The same goes for retrieving debug descriptions and mirrors. Any
value can do that. It is just that some values can opt into
customizing this behavior.

Thus, we renamed the protocols, adding the Custom~ prefix. Our
intention was to encourage only conformances to these protocols, and
discourage writing APIs against them.

Dmitri

--
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr@gmail.com>*/
_______________________________________________
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


(Xiaodi Wu) #10

How do you mean?

···

On Fri, Jul 1, 2016 at 14:44 David Sweeris <davesweeris@mac.com> wrote:

Maybe... It's just a property, though. I *think* if something's moving
into the Syntax thing, I'd rather look for a way to move string
interpolation there. Maybe.

- Dave Sweeris

On Jul 1, 2016, at 14:24, Xiaodi Wu via swift-evolution < > swift-evolution@swift.org> wrote:

Perhaps another candidate for sinking into `Syntax`?
On Fri, Jul 1, 2016 at 14:23 Dmitri Gribenko via swift-evolution < > swift-evolution@swift.org> wrote:

On Fri, Jul 1, 2016 at 12:16 PM, Eric Habberstad via swift-evolution >> <swift-evolution@swift.org> wrote:
>
> To the Swift community,
>
> May I put forth a couple of new names for the following protocol:
>
>
> - CustomStringConvertible — rename as ‘Descriptive’ or as
‘Revealable’
>
>
> Two goals for Swift is clarity and joy in use of the language, so I
strongly
> feel that ‘Custom-‘ not be part of any new name here since it
contributes
> little except verbosity

Hi Eric,

This protocol was called Printable before, but it caused a lot of
confusion for developers, and was guiding the developers toward
writing incorrect APIs. We have seen a lot of developers writing code
like this:

func printAll(_ values: [Printable]) {
  for v in values { print(v) }
}

This code is unnecessarily restrictive since in Swift everything can
be converted into a String.

func printAll(_ values: [Any]) {
  for v in values { print(v) }
}

The same goes for retrieving debug descriptions and mirrors. Any
value can do that. It is just that some values can opt into
customizing this behavior.

Thus, we renamed the protocols, adding the Custom~ prefix. Our
intention was to encourage only conformances to these protocols, and
discourage writing APIs against them.

Dmitri

--
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr@gmail.com>*/
_______________________________________________
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


(David Sweeris) #11

As I understand things, the point of the whole “Syntax.Literal.ICan’tRememberWhatIt’sCalledToday” discussion was that syntactically speaking, literals kinda work the opposite as how everyone thinks they do. That’s not the case here; CustomStringConvertible clearly only requires `var description: String {get}`. But the String interpolation “operator", “\()” might be a good candidate for moving into “Syntax”, if we ever decide it should be able to interact with types other than `T` and `T: CustomStringConvertible`. Well, IMHO, it probably should get moved there regardless, but “my humble opinion" does not make for a convincing proposal on its own (which is unfortunate, IMHO :smiley: ).

- Dave Sweeris

···

On Jul 1, 2016, at 2:47 PM, Xiaodi Wu <xiaodi.wu@gmail.com> wrote:

How do you mean?
On Fri, Jul 1, 2016 at 14:44 David Sweeris <davesweeris@mac.com <mailto:davesweeris@mac.com>> wrote:
Maybe... It's just a property, though. I think if something's moving into the Syntax thing, I'd rather look for a way to move string interpolation there. Maybe.

- Dave Sweeris

On Jul 1, 2016, at 14:24, Xiaodi Wu via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:

Perhaps another candidate for sinking into `Syntax`?
On Fri, Jul 1, 2016 at 14:23 Dmitri Gribenko via swift-evolution <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:
On Fri, Jul 1, 2016 at 12:16 PM, Eric Habberstad via swift-evolution >> <swift-evolution@swift.org <mailto:swift-evolution@swift.org>> wrote:
>
> To the Swift community,
>
> May I put forth a couple of new names for the following protocol:
>
>
> - CustomStringConvertible — rename as ‘Descriptive’ or as ‘Revealable’
>
>
> Two goals for Swift is clarity and joy in use of the language, so I strongly
> feel that ‘Custom-‘ not be part of any new name here since it contributes
> little except verbosity

Hi Eric,

This protocol was called Printable before, but it caused a lot of
confusion for developers, and was guiding the developers toward
writing incorrect APIs. We have seen a lot of developers writing code
like this:

func printAll(_ values: [Printable]) {
  for v in values { print(v) }
}

This code is unnecessarily restrictive since in Swift everything can
be converted into a String.

func printAll(_ values: [Any]) {
  for v in values { print(v) }
}

The same goes for retrieving debug descriptions and mirrors. Any
value can do that. It is just that some values can opt into
customizing this behavior.

Thus, we renamed the protocols, adding the Custom~ prefix. Our
intention was to encourage only conformances to these protocols, and
discourage writing APIs against them.

Dmitri

--
main(i,j){for(i=2;;i++){for(j=2;j<i;j++){if(!(i%j)){j=0;break;}}if
(j){printf("%d\n",i);}}} /*Dmitri Gribenko <gribozavr@gmail.com <mailto:gribozavr@gmail.com>>*/
_______________________________________________
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 <mailto:swift-evolution@swift.org>
https://lists.swift.org/mailman/listinfo/swift-evolution