README: Please clarify "Why Eclipse Collections?" (comparison regarding fluent APIs, etc)

[Chealer]

Background

My organization has a mission system mostly written in a dated Java, which heavily uses the collection framework. Looking at modern Java, the addition of the Stream API certainly helps, but it seems to me that things which should be simple remain awkwardly complicated, as in the following:

// List of strings to make uppercase
List lowercaseWords = Arrays.asList("One", "would", "think", "this", "would", "be", "simple");
List uppercase = list.stream().map(String::toUpperCase).collect(Collectors.toList());

EC seems to allow a natural way to handle this, which is very interesting. On the other hand, fully migrating to EC would involve retraining our developers when our existing stack is already complicated enough, accepting some obscure/awkward-looking class names, and significant refactoring. One also wonders if there's a good reason why EC (or its functionality) is not provided by Java EE. We don't want to complexify our stack, make the packages heavier and increase our maintenance costs without good reasons. A good comparison with the standard collection framework would help us a lot to take the right decision.

What seems to come closest to that is the Why Eclipse Collections? section of the README, which contains:

• Productivity
  • Rich, functional, and fluent APIs with great symmetry
  • List, Set, Bag, Stack, Map, Multimap, BiMap, Interval Types
  • Readable, Mutable, and Immutable Types
  • Mutable and Immutable Collection Factories
  • Adapters and Utility classes for JCF Types

However, my understanding is that Java's Stream API is already fluent. It also provides at least list, set and map types, so at least the first 2 subitems visibly do not compare against standard Java.

Please clarify what this section contains―is it a comparison with Java SE, with other third-party alternatives (which?)... or even a comparison with stacks not based on Java (like Visual Basic)?

By the way

Just by the way, I do not master Java, but have been using it for a couple years and don't remember ever seeing the "JCF" acronym before. Since it's also not defined in the README, on Acronym Finder nor on Wikipedia/Wiktionary, I recommend spelling it out (or replacing with a different term, like "built-in types").

[BrijeshPatra]

Hello @Chealer

Updated the README file

• Clarifications in the "Why Eclipse Collections?" section.
• Improved explanations about the project's advantages and features.
• Addressed feedback and suggestions for enhanced readability.

Please take your time to review the changes, and if there are any further adjustments needed or if you have additional suggestions, I'm open to making them.

Thank you for your time and consideration.

Best regards,
Brijesh Patra

[Chealer]

Thank you @BrijeshPatra but I cannot see your changes...

[BrijeshPatra]

[BrijeshPatra]

Hello @Chealer I made these changes also successfully made the commit. Please let me know what is the issue from my side that you unable to see these changes. It would be very helpful for me if you tell me where I made fault.

[Chealer]

The README's history doesn't show any change in the last 2 weeks. Could you share the URL you are using to visualize your changes?

Thanks for your screenshots already; what I can see from them is promising, but I am pretty sure there should be no asterisk on line 36. An asterisk starts a new list item. Also, it should not end with a colon (":"). A colon can introduce a sentence fragment or a list, but it should not be right before a new section (paragraph). A full stop (".") would suffice.

[BrijeshPatra]

f90ec29

Thanks @Chealer for your guidance and sorry for that asterisk and colon. Will improve it ASAP but go through the link once which I provided I hope you will be able to see my commits.

[Chealer]

Thanks @BrijeshPatra I can indeed see your commit now.

No problem.
At first sight, here are my remarks:

1. Presentation: There is no need for that section to consist in nothing but lists. At least the Comprehensive Collection Types and Compatibility with Java Collections subsections as they stand in your proposal would be much better as bare paragraphs (just sentences).
2. Content: I am not sure what kind of symmetry "These APIs offer great symmetry," refers to. I believe clarifying would help, perhaps with an example.
3. Content: I fail to understand the sense of the sentence "Eclipse Collections is not limited to Java SE; it's a versatile library that can be valuable in a wide range of applications." What do you mean by "limited to Java SE"?

Also, there may be a good reason to remove the links on "Rich", and to types in the Comprehensive Collection Types subsection, but I find it non-obvious and recommend to explain it in the commit message.

By the way (this is pre-existing), "Memory Efficient" should read "Memory-efficient".

[donraab]

Thanks for the feedback @Chealer. The README was in need of some improvements. I have updated and improved the compatibility table as Java 21 will released in a couple of days. We found and reported a serialization bug in Java 21 in our Eclipse Collections serialization tests, and have validated the bug has been fixed in time for the Java 21 release.

I have made a few minor text updates and added links to blogs for various bullets to provide more explanation depth for folks who want to know more. I dropped "symmetry" from the "Productivity" section altogether. Symmetry is not a great selling point for the library, but it is something developers who use the library extensively may learn to appreciate. I hope some of the blog links I added will help add more explanation depth to the "why" of Eclipse Collections. There is a blog @motlin wrote a while back explaining a bit why folks may still need a new collections framework post the existence of Java Streams.

Thank you for your interest in updating the README @BrijeshPatra. We were not looking to make substantive changes to the README right now. We'd like to keep the README fairly concise, which is why we have a list of relatively short bullets. There are still some cosmetic things I didn't change yet that @Chealer pointed out that could be fixed. We could explain that JCF stands for Java Collections Framework and Memory Efficient could be changed to Memory-efficient. If you'd like to submit a PR for any cosmetic changes, I would be happy to review, approve and merge them.

[Chealer]

Thank you very much @donraab that really improves the README. Another aspect which could use copy-editing would be capitalization, which is currently inconsistent at best. Here are some remarks on the format of these changes:

1. The Maturity item seems unnecessarily verbose. It seems like both sub-items say the same thing slightly differently. Surely one of them could be discarded, or they could be merged in a simple (single-sentence?) paragraph. In any case, sentences should be terminated with a full stop (".") and the last sub-item's current phrasing is awkward.
2. The second "c" in "Eclipse Collections" should be capitalized.
3. A blog is a collection of (blog) posts/entries. "Blog:" instances could be replaced by "Blog post:", but I am not sure that indicating which type of content these links are is really helpful. A blog post is usually something fairly time-sensitive, and I feel like these articles are not so time-sensitive (and if they are, putting them in that section is questionable). I would suggest introducing them with a simpler label like "Further reading:" or "More:", but putting the title in italics would be a good idea.

Otherwise, the post from Craig Motlin you mention is very interesting. If the section consisted of that post, this issue would not exist, as it would be clear what EC would be compared to. I really wish that post could somehow be integrated in the section.

[Chealer]

I'm sorry, I don't want to make this request even more complicated, but I'm just noting that the ASF offers Apache Commons Collections.