Preposition Preference | by Donald Raab | JavarevisitedSitemapOpen in appSign up<br>Sign in

Medium Logo

Get app<br>Write

Search

Sign up<br>Sign in

Javarevisited

A humble place to learn Java and Programming better.

Preposition Preference

Donald Raab

5 min read·<br>Nov 15, 2017

Listen

Share

What’s up? A preposition.<br>Press enter or click to view image in full size

Photo taken at Grounds for Sculpture in Hamilton, NJA friend of mine at Rutgers University would always respond to the question “What’s up?” with the consistent response: “A preposition.” I fell into this trap far too many times.<br>Have you ever thought about how much we use prepositions in our Java APIs?<br>We use several different prepositions in methods in Eclipse Collections. Each one conveys a different meaning. Some prepositions that appear in Eclipse Collections multiple times are with, of, by, as, to, from, into. When we use a preposition in a method name, it should help convey meaning clearly. If it doesn’t, then we would have been better off without it.<br>Two prepositions enter. One preposition leaves.<br>At JavaOne this year, I described a battle we once had between two prepositions for naming our collection factory methods in the Eclipse Collections API. The battle was between of and with.<br>MutableList list = Lists.mutable.of("1", "2", "3");

vs.

MutableList list = Lists.mutable.with("1", "2", "3");After an intense debate, we wound up with both options for our collection factory classes. We thought this was one place where we could provide multiple options to allow developers to use their own preference. This however was not the end of the story. Sometimes there is more than just a single battle to be won.<br>The prepositions of and with both work well for naming factory methods for creating collections. I personally prefer with, mostly because this is what was used with Smalltalk. In Smalltalk, I would regularly write the following:<br>|set|<br>set := Set with: '1' with: '2' with: '3'.The following is the equivalent using Java with Eclipse Collections.<br>MutableSet set = Sets.mutable.with("1", "2", "3");If you prefer, you can also create a collection using the of factory method.<br>MutableSet set = Sets.mutable.of("1", "2", "3");There are also forms that take an Iterable as a parameter. These are called ofAll and withAll.<br>In java.util.Collection, there are methods for adding and removing elements to and from collections. They are named add, addAll, remove and removeAll. These four methods return boolean. This makes them unsuitable for writing code fluently.<br>We have our own Mutable interfaces in Eclipse Collections, so we knew we could fix the fluency problem by using one of the two prepositions. We decided to go with with, because with has a natural opposite named without.<br>Set set =<br>Sets.mutable.with("1", "2", "3")<br>.with("4")<br>.without("2");

Assertions.assertEquals(Sets.mutable.with("1", "3", "4"), set);This naming pattern also worked well when adding elements via an Iterable.<br>Set set =<br>Sets.mutable.with("1", "2", "3")<br>.withAll(Lists.mutable.with("4"))<br>.withoutAll(Lists.mutable.with("1", "3"));

Assertions.assertEquals(Sets.mutable.with("2", "4"), set);As you can see, we have with, withAll, without and withoutAll as instance methods directly on our mutable collections. Instead of returning boolean like add or remove, these methods return this, which is the collection that the method is operating on. These methods have good symmetry with the existing methods on Collection that return boolean, and also with each other.<br>We extended this pattern to our immutable collections as well.<br>ImmutableSet set =<br>Sets.immutable.with("1", "2", "3")<br>.newWithAll(Lists.mutable.with("4"))<br>.newWithoutAll(Lists.mutable.with("1", "3"));

Assertions.assertEquals(Sets.mutable.with("2", "4"), set);In the mutable case, the withAll and withoutAll methods mutate the existing collection. In the newWithAll and newWithoutAll cases, a new collection is returned each time, thus preserving the immutability of the original collection.<br>Attack Of the Clones<br>The preposition of lost the battle of the instance-based collection factory methods in Eclipse Collections, because there is no good natural opposite for of like there is for with. That said, of is sometimes an important part of other method names in the Eclipse Collections API.<br>// Bag API - occurrencesOf<br>MutableBag bag = Bags.mutable.with("1", "2", "3");<br>Assertions.assertEquals(1, bag.occurrencesOf("2"));

// List API - indexOf<br>MutableList list = Lists.mutable.with("1", "2", "3");<br>Assertions.assertEquals(1, list.indexOf("2"));

// RichIterable API - sumOfInt, sumOfLong, sumOfFloat, sumOfDouble<br>MutableList list = Lists.mutable.with("1", "2", "3");<br>long sum = list.sumOfInt(Integer::parseInt);<br>Assertions.assertEquals(6L, sum);

// RichIterable API - selectInstancesOf<br>MutableList list = Lists.mutable.with("1", "2", "3");<br>MutableList filtered = list.selectInstancesOf(String.class);<br>Assertions.assertEquals(list, filtered);Revenge of the With<br>Press...