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

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

Leave a Comment