Grammatically correct double-noun identifiers, plural versions

Question

Consider compounds of two nouns, which in natural English would most often appear in the form "noun of noun", e.g. "direction of light", "output of a filter". When programming, we usually write "LightDirection" and "FilterOutput".

Now, I have a problem with plural nouns. There are two cases:

1) singular of plural

e.g. "union of (two) sets", "intersection of (two) segments"

Which is correct, SetUnion and SegmentIntersection or SetsUnion and SegmentsIntersection?

2) plural of plural

There are two subcases:

(a) Many elements, each having many related elements, e.g. "outputs of filters"

(b) Many elements, each having single related element, e.g. "directions of vectors"

Shall I use FilterOutputs and VectorDirections or FiltersOutputs and VectorsDirections?

I suspect correct is the first version (FilterOutupts, VectorDirections), but I think it may lead to ambiguities, e.g.

• FilterOutputs - many outputs of a single filter or many outputs of many filters?
• LineSegmentProjections - projections of many segments or many projections of a single segment?

What are the general rules, I should follow?

Pomelo

I wouldn't use FilterOutput(s) because Filter is ambiguous: noun or verb? – Aphaeresis

I mean Filter is a noun as in "direct show filter". – Pomelo

I know that you mean filter is a noun in your specific case. But a developer new to your project could have to think twice before understanding it when maintaining your code. – Aphaeresis

I don't mean to be a dick, but offering a bounty to advise you on YOUR personal preference is a bit over the top. 99% of agonising questions about coding style on SO can be answered with one word - consistency. – Cilice

Where's the belongs on irosetta.com close option? ;-) – Citizenry

Answer 1

There's a grammatical misunderstanding lying behind this question. When we turn a phrase of form:

1. X of Y

into

2. Y X

the Y changes grammatical role from a noun in the possessive (1) to an adjective in the attributive (2). So while one may pluralise both X and Y in (1), one may only pluralise X in (2), because Y in (2) is an adjective, and adjectives do not have grammatical number.

Hence, e.g., SetsUnion is not in accordance with English. You're free to use it if it suits you, but you are courting unreadability, and I advise against it.

Postscript

In particular, consider two other possessive constructions, first the old-fashioned construction using the possessive pronoun "its", singular:

3a. Y, its X

the equivalent plural:

4a. Ys, their X

and their contractions, with 4b much less common than 3b:

3b. Y's X
4b. Ys' X

Here, SetsUnion suggests it is a rendering of the singular possessive type (3) Set's Union (=Set, its Union), where you intended to communicate the plural possessive (4) Sets, their Union (contracted to the less common Sets' Union).

So it's actively misleading.

Gloxinia

Makes sense. So the choice I have is: (1) Use typical form "Y X" and be inaccurate in some cases or (2) Use "X of Y", which is always accurate, but not programming-typical. – Pomelo

@Michal: Right. Or give up on LongDescriptiveNaturalEnglishNames and come up with your own jargon. If you can have "+" in your identifiers, you could use "SetUnion" vs. "SetUnion+", where the "+" postfix indicates an operation that has been "raised" to an operation on many objects. The trouble is that by killing punctuation, camel case kills distinctions we are used to in normal writing. – Gloxinia

Answer 2

Using plural forms of nouns can make them more difficult to read.

When you have a number of things, they are usually stored in a datastructure - an array, a list, a map, set, etc.. generically called a collection or abstract data type. The interface to a collection of items is typically part of the programming environment (e.g. Collections in java and .net, STL in C++) and is well understood by developers to involve quantities of items.

You can avoid pluralizing your nouns, and make the fact that you are dealing with multiple quantities explicit, and indicate how they are accessed by incorporating the name of the collection. For example,

• VectorDirectionList - the vectors and their directions are listed, e.g. some kind of Pair type. Works particularly well if you have a VectorDirection, combining a Vector and a Direction.
• VectorDirectionMap - if the vector directions are mapped from vector.

Because it's a collection type, dealing with multiple objects is understood as it is endemic to a collection type. It then puts it in the same class as SetUnion - a union always involves at least 2 sets, and a VectorDirectionList makes it clear there can be more than one VectorDirection.

I agree about avoiding homonyms where the word has more than one word class, e.g. Filter, (and actually, Set, although to my mind Set would not really be used in a class name as a verb, so I interpret it as a noun.) I originally wrote this using FilterOutput as an example, but it didn't read well. Using a compound for Filter may help disambiguate - e.g. ImageFilterOutputs (or applying my own adivce, this would be ImageFilterOutputList.)

Avoiding plural forms with class names seems natural when you consider that an instance of a class is itself always one item - "an instance". If we use a plural name, then we get a mismatch - an instance trying to imply that it is multiple things - it itself is just one thing, even if it references multiple other things. The collection naming above builds on this - you have an instance which is a list, a map etc so there is no mismatch.

I'm assuming you are talking about programming language constructs, although the same thinking applies to tables/views. These are understood to involve quantities of items and table names are consequently often singlular (Customer, Order, Item) even though they store multiple rows. Many-to-Many Mapping tables are usually compounds of the entities being related, e.g. relating orders to items - OrderItem. In my experience, using plurals for table names makes the SQL difficult to read.

To sum up, I would avoid plural froms as they make reading harder. There are sure to be cases where they are unavoidable - where using the plural form is more readable than creating a huge name of nested entities and collections, but these are the exception than the rule.

Vincevincelette

I originally wrote "Pluralizing nouns makes them harder to read". I changed it. Verbalizing nouns is also pretty poor writing style! :-) – Vincevincelette

Note that including the type (list/map) in the identifier name is considered overkill by some due to IDE mouse-over assistance and potential mismatch of type to suggested-type after a type change. – Eared

I see your point, although in my experience it's not that often a list is changed to a map, The essence is to find a noun so that plurality is clear, yet the nouns themselves don't need to be plural. – Vincevincelette

This pretty much sums up my opinion. Use a suffix to indicate plurality rather than making the noun plural. So, UnionSetCollection, CustomerCollection etc. If they are lists, then use List as the suffix. If another developer sees FilterOutput and FilterOutputCollection, it should be clear enough which one is a singular instance and which one is plural. – Dicks

But how to distinguish between OutputsOfFilter and OutputsOfFilters? FiltersOutputList and FilterListOutputList?! – Pomelo

Answer 3

Unless you're getting hamstrung by a convention driven system (ruby on rails, cakePHP etc), why not use OutputsOfFilters, UnionOfSets etc? They may not be conventional but they may be clearer.

For example its pretty clear that ProjectionOfLineSegments and ProjectionsOfLineSegment are different things or even ProjectionsOfLineSegments....

Ergosterol

"X of Y" is clear, but I find it inconsistent with what all (afaik) programming libraries use. E.g. .NET uses EventHandler (not HandlerOfEvents), HelpProvider (not ProviderOfHelp), FileAttributes (not AttributesOfFile), ValueType (not TypeOfValue). – Pomelo

Answer 4

What are the general rules, I should follow?

1. Make it Clear -- for both visual and aural thinkers.
2. Make it Specific but Accurate.
3. Make it pass the "crowded room" or "emergency phone call" test.

To illustrate with the SetsUnion example:

• "SetsUnion" is right out; It's easily confused for a typo and speaking it (even in your head) will confuse it for "Set's Union" (Or worse).

• The plural is also implied, so the 2nd 's' is redundant. SetUnion is better but still ambiguous.

• UnionOfSets is clearer and should be the bare minimum standard.

• But all of these, so far, are uselessly vague (unless you are working with pure mathematical theory).
  The term really should be specific. For example, "Red cars", "Programmers who spent too much time on esoterica", etc.
  These are all unions of sets, but they tell you something useful. ;-)

.
Finally, Phil Factor had the right of it. To paraphrase:

Can you shout a (term) out across a crowded room and have it keyed in, and successfully (used), by a listener at the other side?

Try yelling, "SetsUnion," or even, "UnionOfSets," across a packed Irish bar. ;-)

Seminary

Answer 5

What's wrong with Union()?

Moreover, "union of sets" turns into "sets' union" (the two sets' union is ...); I'm sure I'm not the only person who's okay with CamelCase but not CamelsCaseMinusApostrophes. If it needs an apostrophe to make sense, don't use it. Set.Union() reads exactly like "union of set(s)".

Mathematations will also say "the (set) union of A and B", or rarely "A and B's (set) union". "The sets' union of A and B" makes no sense!

Most people will also see Vector[] vectors and Directions[] vectorDirections and assume that vectors[i] corresponds to vectorDirections[i]. If things really get ambiguous, I use something like vector_by_index and vectorDirection_by_index. Then you can have Map<Filter,Output> output_by_filter or Map<Filter,Output[]> outputs_by_filter, which makes it very obvious what the key is (this is very important in Objective-C where it's completely non-obvious what type the keys or values are).

If you really want, you can add an s and get vectors_by_index, but then consistency gives you the silly outputss_by_filter.

The right thing is, of course, something like struct FilterState { Filter filter; Output[] outputs; }; FilterState[] filterStates;.

Redaredact

Answer 6

1) i would use SetUnion and SegmentIntersection because i think in this case the plurality is implied anyway and it just looks nicer that way.

2) again, i would use FilterOutputs and VectorDirections, for the same reason. you could always use MultipleFilterOutputs if you want to be more specific.

but ultimately it's entirely down to your personal preference.

Hillock

Are you sure both VectorDirections and VectorsDirections are correct? – Pomelo

Answer 7

I think that while general naming conventions and consistency are important, but in a very very tight/tricky algorithm, clarity should trump convention. If it helps, use veryLongAndDescriptiveIdentifiers.

Eared

I much prefer writing code so it's easier to maintain by someone familiar with the algorithm; someone unfamiliar won't be helped much by really long identifiers and it only makes it harder to read by someone who does understand it. I'm not sure what you mean by "tight", but in general I find that useful length of an identifier increases with its scope. Loop counter in a short loop? One letter. Instance variable? Probably more. If you need to explain the algorithm, do so in comments. – Redaredact

Tight might be replaced by "dense" - if that helps.... That's an interesting point about the scope-to-length relationship. – Eared

Answer 8

I'd suggest singular for the first word: SetUnion, VectorDirections, etc.

Do a quick class search in your IDE, for: Strings*, Sets*, Vectors*, Collections*

Anyway, whatever you choose, be consistent throughout the whole application.

Ridgeway