Blog article about the new collections #909
Conversation
| [this blog post](/blog/2017/11/28/view-based-collections.html). | ||
|
|
||
| The good news is that the new design is more **correct** in the sense that you can | ||
| now implement custom non-strict collection types without having to worry about |
There was a problem hiding this comment.
Is there some documentation somewhere with more details on this? Which collection traits are safe to extend for non-strict collections and which aren't? E.g. scala.collection.immutable.Set#concat looks strict to me.
There was a problem hiding this comment.
Only traits whose name is prefixed with StrictOptimized are not safe to extend for non-strict collections. The code you’ve linked should be moved to such a trait (it should not be in SetOps but in StrictOptimizedSetOps).
julienrf
force-pushed
the
collections-summary
branch
from
596bea4 to
7f3f7c9
Compare
julienrf
changed the title
| --- | ||
|
|
||
| One more article about the standard collections, really? Indeed, during the last | ||
| 18 months a lot of work has been done on the collections and we’ve published |
There was a problem hiding this comment.
s/on the collections/on the collections side/g reads better?
| One more article about the standard collections, really? Indeed, during the last | ||
| 18 months a lot of work has been done on the collections and we’ve published | ||
| several blog articles and given several talks to the explain various changes or | ||
| challenges we were facing. This article attempts to summarize **what is going |
There was a problem hiding this comment.
we were facing with its design and migration?
| that might have some visible impact on the surface. Then, I will show why I think | ||
| that the removal of `CanBuildFrom` made the API more beginner friendly. Next, I | ||
| will introduce some new operations available in the collections. Finally, I | ||
| will mention the main deprecations, the motivation behind them, and their |
|
Thanks for the feedback Jorge! |
|
|
||
| ## Under The Hood: A Cleaner Ground | ||
|
|
||
|  |
There was a problem hiding this comment.
I don’t know if there is license for it :(
|
|
||
| In case you’ve thoroughly followed our previous blog posts and talks, you might | ||
| not learn much from this article. Otherwise, this is the perfect opportunity | ||
| to catch up on the topic in a few minutes! |
There was a problem hiding this comment.
you could turn this around a bit, and phrase it more positively. first say it is an introduction for everyone, and then something like "even if you've thoroughly followed our previous blog posts and talks, this article gives you a good overview for summarizing the changes to your colleagues".
julienrf
force-pushed
the
collections-summary
branch
from
7f3f7c9 to
4e721c9
Compare
| to change from an end-user perspective**. | ||
|
|
||
| Even if you have thoroughly followed our previous blog posts and talks, this article | ||
| gives you a good overview for summarizing the changes to your colleagues. |
There was a problem hiding this comment.
Maybe remove the "summarizing to your colleagues" point? Seems a bit patronizing 🙊
| don’t use `CanBuildFrom` anymore. I believe this will be quite visible despite our previous | ||
| efforts to *hide* `CanBuildFrom` from the API documentation in the current collections. | ||
| Indeed, if you take a look at the | ||
| [current `List` API](/api/2.12.6/scala/collection/immutable/List.html), the signature |
There was a problem hiding this comment.
Maybe instead of saying "current API" here, you can instead say "old 2.12.x API". It's confusing to say "current"–this wording will only be valid between now and the release of 2.13, and then it will get ultra confusing. So I'd just future-proof everything and say "old" now and indicate that we're talking about 2.12.x
There was a problem hiding this comment.
What about just “2.12 List API”, because it’s not really gonna be old before 2019?
There was a problem hiding this comment.
I still think that saying "old" is better because it reinforces that this is changing. Whether 2.13 comes before 2019 or not, 2.12 is indeed the "old way" to implement collections. Might as well say it here.
| the various possible return types. | ||
|
|
||
| In the new collections we wanted to have simpler type signatures so that we | ||
| can shoulder their actual form in the API documentation and auto-completion |
There was a problem hiding this comment.
Shoulder their actual form? Do you mean show their actual form? I don't understand this wording...
There was a problem hiding this comment.
Haha, sorry I’ve used a word translator but I probably picked a wrong translation… I wanted to say something like “afford” or “assume”.
| In the new collections we wanted to have simpler type signatures so that we | ||
| can shoulder their actual form in the API documentation and auto-completion | ||
| provided by IDEs is not scary. We achieve that by using overloading, as | ||
| explained in more details in |
There was a problem hiding this comment.
Explained in more detail (not plural)
| These type signatures are the actual ones and they essentially translate | ||
| “in types” what I’ve written above about the possible result types of `map` | ||
| according to the type of elements returned by the transformation function `f`. | ||
| I believe that the new API is simpler to understand. |
There was a problem hiding this comment.
Why not say "We believe..."
|
|
||
| ### Insertion And Removal Operations Are Not Available On Generic Collections | ||
|
|
||
| In the current framework, the `scala.collection.Map` type has a `+` and a `-` operations |
There was a problem hiding this comment.
Again, don't say "current" here. Say "old 2.12.x"...
|
|
||
| ### `groupMap` | ||
|
|
||
| A common pattern with the current collection is to use `groupBy` |
There was a problem hiding this comment.
Again, don't say "current" like this.
| Having all these operations can be handy in some cases but can also introduce confusion. If you want | ||
| to use `+` or `-`, then you probably wanted to use an immutable collection type in the first place… | ||
| Another example is the `updated` operation, which is available on mutable `Map` but returns a new | ||
| collection. |
There was a problem hiding this comment.
Can you add a summarizing sentence saying exactly which methods were deprecated from which entities here? Just so it's as clear as possible for anyone skimming.
There was a problem hiding this comment.
That would be something like: “+, -, updated have been moved from scala.collection.Map to scala.collection.immutable.Map, and + and - have been moved from scala.collection.Set to scala.collection.immutable.Set”. Should I replace the sentence line 194 with that?
|
|
||
| We think that by deprecating these insertion and removal operations from generic collection | ||
| types and by having distinct operations between the `mutable` and `immutable` branches we make | ||
| the situation clearer. |
There was a problem hiding this comment.
You might also want to say what the plan is going forward with the deprecations. Usually when methods that people use are deprecated, we tell them precisely for which version of Scala they will be deprecated, and for which version of Scala they will be removed.
| (no implicit `CanBuildFrom` parameter), | ||
| - new cool operations have been added, | ||
| - the type hierarchy is simpler (no `Traversable`), | ||
| - mutable collection types do not inherit immutable insertion and removal operations. |
There was a problem hiding this comment.
Again, be more precise about in which version of Scala which specific methods will be deprecated, and in which version of Scala they will be removed.
|
|
||
| One more article about the standard collections, really? Indeed, during the last | ||
| 18 months a lot of work has been done on the collections and we’ve published | ||
| several blog articles and given several talks to the explain various changes or |
There was a problem hiding this comment.
to explain the various changes and challenges we were facing?
| to catch up on the topic in a few minutes! | ||
|
|
||
| The next section presents the internal changes in the collections implementation | ||
| that might have some visible impact on the surface. Then, I will show why I think |
There was a problem hiding this comment.
How about: The next section presents the changes that are internal to the implementation of the collections, but might have some visible impact on the surface.
| the various possible return types. | ||
|
|
||
| In the new collections we wanted to have simpler type signatures so that we | ||
| can shoulder their actual form in the API documentation and auto-completion |
There was a problem hiding this comment.
Is shoulder a typo here? I didn't know this verb, it looks like it means "accept the responsibility for something". Does that make sense here?
There was a problem hiding this comment.
I'd simply say "so that we can show their actual signature in the API, and have IDEs show reasonable completions"
| We felt that having a distinction between `Traversable` and `Iterable` was not | ||
| worth it, so we removed `Traversable` (it is now an alias to `Iterable[A]`). | ||
|
|
||
| `IterableOnce[A]` is now the collection type at the top of the hierarchy. |
There was a problem hiding this comment.
The section title says that Iterable is the top type?
julienrf
force-pushed
the
collections-summary
branch
from
e81c577 to
4b534df
Compare
|
I think I’ve addressed all your feedback @heathermiller |
|
Looks like you've got some linking errors... |
|
The links are incorrectly flagged as broken. I’ve pushed a workaround. |
Do you think there other interesting news that impact end-users and would be worth mentioning?