In Javadocs, how should I write plural forms of singular Objects in <code> tags?

Question

I have a class named Identity. In my javadoc comments I am referencing it as a plural. I can think of two solutions: change the reference to <code>Identities</code> or <code>Identity</code>s. Neither of these feel correct, and I'm wondering if there's a better solution.

Here is an example for clarity:

/**
  * Returns an <code>IdentityBank</code> of <code>Identity</code>s with the given sex.
  */

or

/**
  * Returns an <code>IdentityBank</code> of <code>Identities</code> with the given sex.
  */

Footnote

By the way, since Java 5, you can write {@code IdentityBank}, which is shorter than <code>IdentityBank</code>. – Teno

Answer 1

Use a "...(s)" style plural label, with a {@link} to the class:

/**
  * Returns an {@link IdentityBank} of {@link Identity Identity(s)} with the given sex.
  */

This will render as:

Returns an IdentityBank of Identity(s) with the given sex.

It's easy and more natural to read, and obvious and clear what you are saying.

You should be using {@link} anyway for classes. It takes care of <code> style formatting, and provides an HTML link to the actual class.

---

You could code the "(s)" after the link, ie {@link Identity}(s), meaning a completely conventional usage of {@link}, but there would be a font change mid-word:

Returns an IdentityBank of Identity(s) with the given sex.

which IMHO reduces clarity and could cause confusion.

Furuncle

I don’t like it. It’s misleading because rendered like this it looks like there is an identifier in the code called "Identities" (in the worst case that may even be true). You have to mouse over the link and read the URL to see what’s actually said here, and that’s incredibly poor usability. Imo Robert Columbia’s answer is a much better compromise between correctness and good grammar/typography. – Frostwork

@Frostwork I think Robert's grammar is clumsy, but you've prompted me to improve my answer - see if you like it. Pressure makes diamonds :) – Furuncle

+1: The name of the class is clearly visible now. Beyond that I think a bit of typographical or grammatical awkwardness will remain no matter what. So I’m fine with pretty much all solutions. – Frostwork

Answer 2

It sounds like there are two things you want to do here: use good grammar but also use the literal, verbatim names of your classes so that users of your javadoc may look them up.

One thing you can do when working with plurals is use the phrase "X instances". So using your example, you could put:

/**
 * Returns an <code>IdentityBank</code> of <code>Identity</code> instances with the given sex.
 */

If you need to specify a plural of a value type (which doesn't have instances per se), you can use "X values". For example, you could say "Returns a list of int values". Other acceptable names might be "records", "notes", "entries", "notices", or, as @Marco13 mentioned, "objects".

You should avoid using terms that collide with an existing term of art or class name in your framework, system, or application unless you are using that term as it is already used. For example, do not say "returns a list of Case files" unless you are referring to literal files in a filesystem. Using it to refer to a business rules concept of a file adds potential for confusion. Other terms to consider avoiding for this reason may be "databases", "tables" (unless referring to actual tables in a database or an abstraction or representation of them), "pages", "forms", "sheets", "drivers", "ports", "windows", "lists", "heaps", "stacks", "applications", "exceptions" (unless they are Throwable), "pins", and "buses".

Similarly, any reasonable noun at all is useful if it fits the business rules of the code and is understandable. You could do any of the following:

• Returns a Quadrant of MapNode entries
• Returns a BalancedTree of Employee dossiers

Cardoso

+1: Awkward cases like this are why a lot of technical writing style guides favor treating most code identifiers, product/technology names, etc as adjectives. – Blamable

Agreed: "instances", "values", "objects" - there are several options, and although it may sometimes sound a bit unnatural, it is the least ambiguous form - particularly when the class names are used as a {@link...} – Inveteracy

@Inveteracy exactly. Any reasonable noun at all is useful if it fits the business rules of the code and is understandable. There could be a context for "Returns a Quadrant of MapNode entries" or "Returns a BalancedTree of Employee dossiers". – Cardoso

Answer 3

^{When I saw the question title, I wondered: How can this not have been closed after 5 minutes as "Primarily opinion-based"? But I think it is an important question, and I've been agonizing over this far too much, eventually coming to the conclusion that there may be different (objective, i.e. not opinion-based!) arguments for the different options - so here are my two cents:}

Using the class names Customer and Identity as examples, there are different options, which would be rendered as follows:

1. All Customers have Identitys

   Having the "s" in a different font decreases readability. The wrong plural of "Identity" is questionable.

2. All Customers have Identities

   This may look nice at the first glance. But it has a severe drawback: It is a common practice to append an s to class names for classes that contain factory methods! For example, a class that contains factory methods for Customer objects would, by convention, be called Customers. And a JavaDoc like this...:

   You can create Customers with the methods in the Customers class

   is plainly confusing: The link does not lead to the documentation that you might expect from the name that you are clicking on.

3. The solution that I usually apply (and I already used it above, when talking about the drawback of approach 2.) :

   All Customer objects have Identity objects.

   Yes, it may sound a bit unnatural, but I consider it as the best trade-off: The name Identity is readable, it is obvious that it is a class name, and it is unambigous that the name of the class is Identity.

---

A side note: I usually insert the names as {@link ...}. This is convenient due to the auto-completion in Eclipse, and because it can significantly simplify browsing through the resulting JavaDocs. I'd recommend to use {@link ...} at least the first time when a class name appears in a documentation block. For further appearances, <code>...</code> may be used.

Inveteracy

Answer 4

I usually prefer the third option of Marco13s answer (i.e. {@link …} with some other plural word like "objects") but sometimes the use of {@linkplain …} is also a good alternative:

/**
 * Returns an {@link IdentityBank} of {@linkplain Identity identities} with the given sex.
 */

This would be rendered something like this:

Returns an IdentityBank of identities with the given sex.

This way you know that there is some class that handles identities (and you can find out which by following the link) but it is clear (from the all lowercase spelling and the formatting) that this is not the exact name of the class, in contrast to the verbatim IdentityBank.

(Note: This example may not be the best for this method but it demonstrates the point and usage.)

Think

Answer 5

As suggested in https://developers.google.com/style/api-reference-comments I would use the following:

/**
 * Returns an {@link IdentityBank} of {@link Identity} objects with the given sex.
 */

Though there is the option of the {@link Identity identities} syntax I wouldn't make use of it as one would risk rename refactorings of Identity not being reflected accordingly.
More specifically, if you renamed Identity to Identification you would very likely end up with {@link Identification identities} whereas identities stays unchanged without noting.

Bassarisk