From 16bfa8dbbd5c2f4701389fb2e86ca24ca8d6934b Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Sat, 12 Nov 2016 11:31:20 +0000 Subject: [PATCH 01/11] SIP-27: Simplify the History --- .../_posts/2016-06-25-trailing-commas.md | 15 +++++++-------- 1 file changed, 7 insertions(+), 8 deletions(-) diff --git a/sips/completed/_posts/2016-06-25-trailing-commas.md b/sips/completed/_posts/2016-06-25-trailing-commas.md index 562a968141..4904e70657 100644 --- a/sips/completed/_posts/2016-06-25-trailing-commas.md +++ b/sips/completed/_posts/2016-06-25-trailing-commas.md @@ -14,16 +14,15 @@ vote-text: The following proposal needs to be updated, since only the specialize | Date | Version | | ---------------|-------------------------------------------------| | Jun 25th 2016 | Initial Draft | -| Jun 27th 2016 | Added drawback of changing existing tools | -| Jun 27th 2016 | Added motivation that it simplifies codegen | -| Jun 28th 2016 | Fixed a typo | -| Aug 10th 2016 | Renamed from SIP-NN to SIP-27 | +| Jun 27th 2016 | New drawback: changing existing tools | +| Jun 27th 2016 | New motivation: simplifies codegen | +| Aug 10th 2016 | SIP numbered: Renamed to SIP-27 | | Aug 10th 2016 | Changed scala-commas URL (repo was moved) | -| Aug 10th 2016 | Dialed back some of the language from review | +| Aug 10th 2016 | Dialed back some of the language | | Sep 04th 2016 | Split the motivation into sections | -| Sep 04th 2016 | Add VCS authorship attribution to motivation | -| Sep 04th 2016 | Add Cross building hinderance to drawbacks | -| Sep 12th 2016 | Remove Cross building hinderance from drawbacks | +| Sep 04th 2016 | New motivation: VCS authorship attribution | +| Sep 04th 2016 | New drawback: Cross building hinderance | +| Sep 12th 2016 | Remove cross building hinderance from drawbacks | ## Motivation From d51d757709917ec2c1f7d38e19edb94e828dbcdf Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Sat, 12 Nov 2016 11:52:36 +0000 Subject: [PATCH 02/11] SIP-27: Move back to pending/under review --- sips/completed/_posts/2016-06-25-trailing-commas.md | 4 +++- 1 file changed, 3 insertions(+), 1 deletion(-) diff --git a/sips/completed/_posts/2016-06-25-trailing-commas.md b/sips/completed/_posts/2016-06-25-trailing-commas.md index 4904e70657..78634dfe86 100644 --- a/sips/completed/_posts/2016-06-25-trailing-commas.md +++ b/sips/completed/_posts/2016-06-25-trailing-commas.md @@ -3,10 +3,12 @@ layout: sip disqus: true title: SIP-27 - Trailing Commas -vote-status: accepted +vote-status: under review vote-text: The following proposal needs to be updated, since only the specialized case version (with new lines) has been accepted. For more information, check the minutes. --- +// TODO: Move from sips/completed to sips/pending + **By: Dale Wijnand** ## History From 049df35cbd1b83221c37a1c9ba3649515b79f77c Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Sat, 12 Nov 2016 15:00:23 +0000 Subject: [PATCH 03/11] SIP-27: Major rework: multi-line, 2 variants & spec --- .../_posts/2016-06-25-trailing-commas.md | 143 +++++++++++++----- 1 file changed, 106 insertions(+), 37 deletions(-) diff --git a/sips/completed/_posts/2016-06-25-trailing-commas.md b/sips/completed/_posts/2016-06-25-trailing-commas.md index 78634dfe86..650d8df763 100644 --- a/sips/completed/_posts/2016-06-25-trailing-commas.md +++ b/sips/completed/_posts/2016-06-25-trailing-commas.md @@ -25,10 +25,11 @@ vote-text: The following proposal needs to be updated, since only the specialize | Sep 04th 2016 | New motivation: VCS authorship attribution | | Sep 04th 2016 | New drawback: Cross building hinderance | | Sep 12th 2016 | Remove cross building hinderance from drawbacks | +| Nov 12th 2016 | Major rework: multi-line, 2 variants & spec | ## Motivation -### Easy to modify lists +### Ease of modification When using a comma-separated sequence of elements on multiple lines, such as: @@ -40,33 +41,33 @@ Seq( ) {% endhighlight %} -It is quite inconvenient to remove or comment out any element because one has to think about the fact that the last element mustn't have a trailing comma: +It is inconvenient to remove or comment out elements because the last element mustn't have a trailing comma: {% highlight scala %} -Map( +Seq( foo, - bar //, + bar, // baz -) +) // error: illegal start of simple expression {% endhighlight %} -Secondly, it is quite inconvenient to re-order the sequence, for instance if you wanted `baz` before `bar` you need to micromanage which is followed by a comma and which isn't: +It is also inconvenient to reorder because every element but the last one must be followed by a comma: {% highlight scala %} val xs = Seq( foo, - baz // This isn't going to work + baz bar, -) +) // error: illegal start of simple expression {% endhighlight %} ### Reduce diff noise -Allowing trailing commas also reduces a lot of noise in diffs, such as: +Adding and removing commas also introduces unnecessary noise in diffs: {% highlight diff %} @@ -4,7 +4,8 @@ - Map( + Seq( foo, bar, - baz @@ -77,15 +78,15 @@ Allowing trailing commas also reduces a lot of noise in diffs, such as: ### VCS authorship attribution -Using the example above, the authorship of the `baz` line would be preserved, instead of becoming that of the author of the `quux` line. +Using the example above, adding a comma after `baz` also unnecessarily changed the authorship of the line. ### Simplify code generation -Such a feature would also simplify generating Scala source code. +Allowing trailing commas would also simplify generating Scala source code. ### Long standing ticket -There is an open ticket ([SI-4986][]) where this feature was requested, referencing the fact that it facilitates code generation by tools and allows for easier sorting of the values, initially in the context of import selectors but later also for other constructs in the syntax. +([SI-4986][]) was opened in 2011 requesting support for trailing commas, referencing that it facilitates code generation by tools and allows easier sorting of values. It was initially in the context of import selectors but later also for other constructs in the syntax. ### Real-world use-cases @@ -96,45 +97,113 @@ Some real-world use-cases where elements of a sequence are typically added, remo ## Design Decisions -There are a number of different elements of the Scala syntax that are comma separated, but instead of changing them all a subset of the more useful ones was chosen: +### Multi-line + +It is not the intent of introducing trailing commas to promote a code style such as: + +{% highlight scala %} +val xs = Seq(foo, baz, bar, ) +{% endhighlight %} + +Trailing comma support is therefore restricted to only comma-separated elements that are on separate lines: + +{% highlight scala %} +val xs = Seq( + foo, + baz, + bar, +) +{% endhighlight %} + +### What parts of the Scala grammar to change + +There are a number of different parts of the Scala grammar that are comma-separated and, therefore, could support trailing commas. Specifically: + +* `ArgumentExprs` +* `Params` and `ClassParams` +* `SimpleExpr1` +* `TypeArgs`, `TypeParamClause` and `FunTypeParamClause` +* `SimpleType` and `FunctionArgTypes` +* `SimplePattern` +* `ImportSelectors` +* `Import` +* `Bindings` +* `ids`, `ValDcl`, `VarDcl`, `VarDef` and `PatDef` + +With this proposal I would like to present 2 variants: + +1. The first variant adds trailing comma support to only `ArgumentExprs`, `Params` and `ClassParams`, which I consider to be the parts of the grammar that would most benefit from trailing commas. -* tuples -* argument and parameter groups, including for implicits, for functions, methods and constructors -* import selectors +2. The second variant adds trailing comma support to the whole grammar, which means more consistency, but also supporting trailing commas in places that doesn't really need it, such as `ids`. -From the spec these are: +**NOTE:** I recommend the first variant: only add trailing comma support to `ArgumentExprs`, `Params` and `ClassParams`. -* SimpleExpr1, ArgumentExprs via Exprs -* ParamClause, ParamClauses via Params -* ClassParamClause, ClassParamClauses via ClassParams -* ImportSelector +See below for a summary of what changing `ArgumentExprs`, `Params` and `ClassParams` means. -The elements that have not changed are: +#### Changing `ArgumentExprs` -* ValDcl, VarDcl, VarDef via ids -* Type via FunctionArgTypes -* SimpleType, TypeArgs via Types -* Expr, ResultExpr via Bindings -* SimplePattern via Patterns -* TypeParamClause, FunTypeParamClause -* ImportExp -* PatDef +**Spec change** + +{% highlight diff %} + Exprs ::= Expr {‘,’ Expr} +-ArgumentExprs ::= ‘(’ [Exprs] ‘)’ ++ArgumentExprs ::= ‘(’ [Exprs] [‘,’] ‘)' +{% endhighlight %} + +**Example** +{% highlight scala %} +Seq( + foo, + bar, + baz, +) +{% endhighlight %} + +## `Params` and `ClassParams` + +**Spec change** +{% highlight diff %} + Params ::= Param {‘,’ Param} +- ParamClause ::= [nl] ‘(’ [Params] ‘)’ +-ParamClauses ::= {ParamClause} [[nl] ‘(’ ‘implicit’ Params ‘)’] ++ ParamClause ::= [nl] ‘(’ [Params] [‘,’] ‘)’ ++ParamClauses ::= {ParamClause} [[nl] ‘(’ ‘implicit’ Params [‘,’] ‘)’] + + ClassParams ::= ClassParam {‘,’ ClassParam} +- ClassParamClause ::= [nl] ‘(’ [ClassParams] ‘)’ +-ClassParamClauses ::= {ClassParamClause} [[nl] ‘(’ ‘implicit’ ClassParams ‘)’] ++ ClassParamClause ::= [nl] ‘(’ [ClassParams] [‘,’] ‘)’ ++ClassParamClauses ::= {ClassParamClause} [[nl] ‘(’ ‘implicit’ ClassParams [‘,’] ‘)’] +{% endhighlight %} + +**examples** +{% highlight scala %} +def bippy( + foo: Int, + bar: String, + baz: Boolean, +) + +class Bippy( + foo: Int, + bar: String, + baz: Boolean, +) +{% endhighlight %} ## Implementation -The implementation is a simple change to the parser, allowing for a trailing comma, for the groups detailed above, and has been proposed in [scala/scala#5245][]. +The implementation of trailing commas is a matter of changing some of the implementation of Scala's parser. An implementation of an earlier version of this proposal can be found at [scala/scala#5245][]. ## Drawbacks/Trade-offs -The drawback, or trade-off, to this change is that it adds another way in which it is possible to do something in Scala. But it is the opinion of this SIP that the pragmatic advantage of being able to have trailing commas is worth this drawback. +One drawback, or trade-off, to this change is that it adds an alternative way in which it is possible to do something in Scala. But I believe that the pragmatic advantage of being able to have trailing commas is worth this drawback. -Given that this is a change in syntax, another drawback is that it requires changing the existing tools, such as those that parse Scala: intellij-scala, scalariform, scala.meta and scalaparse. +Another drawback, given this is a change in syntax, is that it requires changing the existing tools, such as those that parse Scala: intellij-scala, scalariform, scala.meta and scalaparse. ## Alternatives -As an alternative, trailing commas support could be added universally to all the comma-separated elements of the syntax. This would mean changing more (but still only in the parser), but it would make it consistent. - -As an alternative to changing the language, there already exists today a compiler plugin called [scala-commas][] that provides this feature. It also provides some evidence that people would even use unsupported compiler apis and reflection to add this functionality, even when such a plugin won't compose with other plugins well, though arguably only weak evidence as it's a young and obscure plugin. +As an alternative to changing the language, there already exists today a compiler plugin called [scala-commas][] that provides a variant of this feature. It also provides some evidence that people would even use unsupported compiler apis and reflection to add this functionality, even when such a plugin won't compose with other plugins well, though arguably only weak evidence as it's a young and obscure plugin. ## References From 3d9f0ea4a3276893ed9d26666ae0961d3f2b3452 Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Sat, 12 Nov 2016 20:27:36 +0000 Subject: [PATCH 04/11] SIP-27: Re-word my recommendation for the first variant --- sips/completed/_posts/2016-06-25-trailing-commas.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sips/completed/_posts/2016-06-25-trailing-commas.md b/sips/completed/_posts/2016-06-25-trailing-commas.md index 650d8df763..e9cce8c3ea 100644 --- a/sips/completed/_posts/2016-06-25-trailing-commas.md +++ b/sips/completed/_posts/2016-06-25-trailing-commas.md @@ -136,9 +136,9 @@ With this proposal I would like to present 2 variants: 2. The second variant adds trailing comma support to the whole grammar, which means more consistency, but also supporting trailing commas in places that doesn't really need it, such as `ids`. -**NOTE:** I recommend the first variant: only add trailing comma support to `ArgumentExprs`, `Params` and `ClassParams`. +In this proposal, only the first variant is considered: trailing comma support for `ArgumentExprs`, `Params` and `ParamClasses` for the sake of simplicity. -See below for a summary of what changing `ArgumentExprs`, `Params` and `ClassParams` means. +See below for more details on what that would mean. #### Changing `ArgumentExprs` From 0066ac4019f2fc145b542792d7c5df5f69611f65 Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Tue, 15 Nov 2016 12:22:10 +0000 Subject: [PATCH 05/11] SIP-27: Be more explicit about multi-line --- sips/completed/_posts/2016-06-25-trailing-commas.md | 4 ++-- 1 file changed, 2 insertions(+), 2 deletions(-) diff --git a/sips/completed/_posts/2016-06-25-trailing-commas.md b/sips/completed/_posts/2016-06-25-trailing-commas.md index e9cce8c3ea..14e4e06a2c 100644 --- a/sips/completed/_posts/2016-06-25-trailing-commas.md +++ b/sips/completed/_posts/2016-06-25-trailing-commas.md @@ -132,9 +132,9 @@ There are a number of different parts of the Scala grammar that are comma-separa With this proposal I would like to present 2 variants: -1. The first variant adds trailing comma support to only `ArgumentExprs`, `Params` and `ClassParams`, which I consider to be the parts of the grammar that would most benefit from trailing commas. +1. The first variant adds trailing comma support to only multi-line `ArgumentExprs`, `Params` and `ClassParams`, which I consider to be the parts of the grammar that would most benefit from trailing commas. -2. The second variant adds trailing comma support to the whole grammar, which means more consistency, but also supporting trailing commas in places that doesn't really need it, such as `ids`. +2. The second variant adds trailing comma support to the whole grammar (again, only for multi-line), which means more consistency, but also supporting trailing commas in places that doesn't really need it, such as `ids`. In this proposal, only the first variant is considered: trailing comma support for `ArgumentExprs`, `Params` and `ParamClasses` for the sake of simplicity. From 206fba0202c3de6957df9ef034629b62b56e507f Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Mon, 21 Nov 2016 11:04:44 +0000 Subject: [PATCH 06/11] SIP-27: Re-word that the impl PR == the current proposal --- sips/completed/_posts/2016-06-25-trailing-commas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/completed/_posts/2016-06-25-trailing-commas.md b/sips/completed/_posts/2016-06-25-trailing-commas.md index 14e4e06a2c..fb3698e99b 100644 --- a/sips/completed/_posts/2016-06-25-trailing-commas.md +++ b/sips/completed/_posts/2016-06-25-trailing-commas.md @@ -193,7 +193,7 @@ class Bippy( ## Implementation -The implementation of trailing commas is a matter of changing some of the implementation of Scala's parser. An implementation of an earlier version of this proposal can be found at [scala/scala#5245][]. +The implementation of trailing commas is a matter of changing some of the implementation of Scala's parser. An implementation of this proposal can be found at [scala/scala#5245][]. ## Drawbacks/Trade-offs From 15e15e358e4e18d6c932d644a6a94b4d843738b2 Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Mon, 21 Nov 2016 11:07:45 +0000 Subject: [PATCH 07/11] SIP-27: Add links to PR numbers .. for those who don't want to re-read the whole document but instead want to see the diff of what changed. --- .../_posts/2016-06-25-trailing-commas.md | 28 ++++++++++--------- 1 file changed, 15 insertions(+), 13 deletions(-) diff --git a/sips/completed/_posts/2016-06-25-trailing-commas.md b/sips/completed/_posts/2016-06-25-trailing-commas.md index fb3698e99b..706fb07953 100644 --- a/sips/completed/_posts/2016-06-25-trailing-commas.md +++ b/sips/completed/_posts/2016-06-25-trailing-commas.md @@ -13,19 +13,19 @@ vote-text: The following proposal needs to be updated, since only the specialize ## History -| Date | Version | -| ---------------|-------------------------------------------------| -| Jun 25th 2016 | Initial Draft | -| Jun 27th 2016 | New drawback: changing existing tools | -| Jun 27th 2016 | New motivation: simplifies codegen | -| Aug 10th 2016 | SIP numbered: Renamed to SIP-27 | -| Aug 10th 2016 | Changed scala-commas URL (repo was moved) | -| Aug 10th 2016 | Dialed back some of the language | -| Sep 04th 2016 | Split the motivation into sections | -| Sep 04th 2016 | New motivation: VCS authorship attribution | -| Sep 04th 2016 | New drawback: Cross building hinderance | -| Sep 12th 2016 | Remove cross building hinderance from drawbacks | -| Nov 12th 2016 | Major rework: multi-line, 2 variants & spec | +| Date | Version | +| ---------------|------------------------------------------------------------| +| Jun 25th 2016 | Initial Draft ([#533][]) | +| Jun 27th 2016 | New drawback: changing existing tools ([#533][]) | +| Jun 27th 2016 | New motivation: simplifies codegen ([#533][]) | +| Aug 10th 2016 | SIP numbered: Renamed to SIP-27 ([#533][]) | +| Aug 10th 2016 | Changed scala-commas URL (repo was moved) ([#533][]) | +| Aug 10th 2016 | Dialed back some of the language ([#533][]) | +| Sep 04th 2016 | Split the motivation into sections ([#533][]) | +| Sep 04th 2016 | New motivation: VCS authorship attribution ([#533][]) | +| Sep 04th 2016 | New drawback: Cross building hinderance ([#533][]) | +| Sep 12th 2016 | Remove cross building hinderance from drawbacks ([#533][]) | +| Nov 12th 2016 | Major rework: multi-line, 2 variants & spec ([#625][]) | ## Motivation @@ -214,3 +214,5 @@ As an alternative to changing the language, there already exists today a compile [SI-4986]: https://issues.scala-lang.org/browse/SI-4986 [scala/scala#5245]: https://github.com/scala/scala/pull/524://github.com/scala/scala/pull/5245 [scala-commas]: https://github.com/47deg/scala-commas +[#533]: https://github.com/scala/scala.github.com/pull/533 +[#625]: https://github.com/scala/scala.github.com/pull/625 From 3f11780a651b9a8009efdfdf097714fdc8e59bbf Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Thu, 24 Nov 2016 09:43:30 +0000 Subject: [PATCH 08/11] SIP-27: Consistent section titles --- sips/completed/_posts/2016-06-25-trailing-commas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/completed/_posts/2016-06-25-trailing-commas.md b/sips/completed/_posts/2016-06-25-trailing-commas.md index 706fb07953..f061f6cb00 100644 --- a/sips/completed/_posts/2016-06-25-trailing-commas.md +++ b/sips/completed/_posts/2016-06-25-trailing-commas.md @@ -61,7 +61,7 @@ val xs = Seq( ) // error: illegal start of simple expression {% endhighlight %} -### Reduce diff noise +### Diff noise reduction Adding and removing commas also introduces unnecessary noise in diffs: From d1ebb53f3257ad27b34d09833af76b2c86872294 Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Thu, 24 Nov 2016 09:51:24 +0000 Subject: [PATCH 09/11] SIP-27: Briefly explain why no single-line trailing commas --- sips/completed/_posts/2016-06-25-trailing-commas.md | 7 +++++++ 1 file changed, 7 insertions(+) diff --git a/sips/completed/_posts/2016-06-25-trailing-commas.md b/sips/completed/_posts/2016-06-25-trailing-commas.md index f061f6cb00..ba15d7e36e 100644 --- a/sips/completed/_posts/2016-06-25-trailing-commas.md +++ b/sips/completed/_posts/2016-06-25-trailing-commas.md @@ -105,6 +105,13 @@ It is not the intent of introducing trailing commas to promote a code style such val xs = Seq(foo, baz, bar, ) {% endhighlight %} +for a number of reasons: + +1. Subjectively, it's an ugly style. +2. Some people utilise commas as a mechanism for counting, so introducing an optional trailing commas interferes with this technique; when elements are one by line, then line-counting can be used. +3. Adding or removing elements is less cumbersome on one line. +4. Commenting out elements isn't any less cumbersome with an optional trailing comma. + Trailing comma support is therefore restricted to only comma-separated elements that are on separate lines: {% highlight scala %} From fbf4172f322fcfefe38bf4d5c3eb0cb697217c20 Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Thu, 24 Nov 2016 09:53:53 +0000 Subject: [PATCH 10/11] SIP-27: Try & clarify the drawbacks of whole grammar trailing comma support --- sips/completed/_posts/2016-06-25-trailing-commas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/completed/_posts/2016-06-25-trailing-commas.md b/sips/completed/_posts/2016-06-25-trailing-commas.md index ba15d7e36e..1c5559da1b 100644 --- a/sips/completed/_posts/2016-06-25-trailing-commas.md +++ b/sips/completed/_posts/2016-06-25-trailing-commas.md @@ -141,7 +141,7 @@ With this proposal I would like to present 2 variants: 1. The first variant adds trailing comma support to only multi-line `ArgumentExprs`, `Params` and `ClassParams`, which I consider to be the parts of the grammar that would most benefit from trailing commas. -2. The second variant adds trailing comma support to the whole grammar (again, only for multi-line), which means more consistency, but also supporting trailing commas in places that doesn't really need it, such as `ids`. +2. The second variant adds trailing comma support to the whole grammar (again, only for multi-line), which means more consistency, but also supporting trailing commas in places that in practice don't really require it as much, such as `ids`. In this proposal, only the first variant is considered: trailing comma support for `ArgumentExprs`, `Params` and `ParamClasses` for the sake of simplicity. From afd70917e72708cb01c36cc9ed89599d72bbb466 Mon Sep 17 00:00:00 2001 From: Dale Wijnand Date: Thu, 24 Nov 2016 09:55:12 +0000 Subject: [PATCH 11/11] SIP-27: Clarify the description of the proposed implementation --- sips/completed/_posts/2016-06-25-trailing-commas.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/sips/completed/_posts/2016-06-25-trailing-commas.md b/sips/completed/_posts/2016-06-25-trailing-commas.md index 1c5559da1b..ca7bb185ab 100644 --- a/sips/completed/_posts/2016-06-25-trailing-commas.md +++ b/sips/completed/_posts/2016-06-25-trailing-commas.md @@ -200,7 +200,7 @@ class Bippy( ## Implementation -The implementation of trailing commas is a matter of changing some of the implementation of Scala's parser. An implementation of this proposal can be found at [scala/scala#5245][]. +The implementation of trailing commas is is limited to changing Parsers.scala in the Scala compiler. An implementation of this proposal can be found at [scala/scala#5245][]. ## Drawbacks/Trade-offs