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.   */ 

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.

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