En Javadocs, ¿cómo debo escribir formas plurales de Objetos singulares en etiquetas<code>?

grammar

Question

Tengo una clase llamada Identity . En mis comentarios de javadoc lo estoy haciendo referencia en plural. Puedo pensar en dos soluciones: cambiar la referencia a <code>Identities</code> o <code>Identity</code> s. Ninguno de estos se siente correcto, y me pregunto si hay una solución mejor.

Aquí hay un ejemplo de claridad:

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

o

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

Answer 1

Parece que hay dos cosas que quieres hacer aquí: usa una buena gramática pero también usa los nombres literales y literales de tus clases para que los usuarios de tu javadoc puedan buscarlos.

Una cosa que puede hacer cuando trabaja con plurales es usar la frase "X instancias". Entonces usando tu ejemplo, podrías poner:

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

Si necesita especificar un plural de un tipo de valor (que no tiene instancias per se), puede usar "valores de X". Por ejemplo, podría decir "Devuelve una lista de valores int". Otros nombres aceptables pueden ser "registros", "notas", "entradas", "avisos" o, como se menciona en @ Marco13, "objetos".

Debe evitar el uso de términos que chocan con un término de arte o nombre de clase existente en su marco, sistema o aplicación, a menos que esté usando ese término como ya se usa. Por ejemplo, no diga "devuelve una lista de archivos de casos" a menos que se refiera a archivos literales en un sistema de archivos. Su uso para referirse a un concepto de reglas de negocios de un archivo aumenta la posibilidad de confusión. Otros términos que debe considerar evitar por esta razón pueden ser "bases de datos", "tablas" (a menos que se refieran a tablas reales en una base de datos o una abstracción o representación de ellas), "páginas", "formularios", "hojas", "controladores" , "puertos", "ventanas", "listas", "montones", "pilas", "aplicaciones", "excepciones" (a menos que sean Throwable ), "pines" y "buses".

De manera similar, cualquier nombre razonable es útil si se ajusta a las reglas comerciales del código y es comprensible. Usted podría hacer cualquiera de los siguientes:

• Devuelve un cuadrante de entradas de MapNode
• Devuelve un dossier de BalancedTree of Employee

Answer 2

Por lo general, prefiero la tercera opción de la respuesta de Marco13 (es decir, {@link …} con otra palabra plural como "objetos"), pero a veces el uso de {@linkplain …} también es una buena alternativa:

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

Esto se traduciría en algo como esto:

Devuelve un IdentityBank de Identities con el sexo dado.

De esta manera, sabrá que hay alguna clase que maneja identidades (y puede averiguar cuál siguiendo el enlace) pero está claro (de la ortografía en minúscula y el formato) que este no es el nombre exacto de la clase, en Contraste con el IdentityBank textual.

(Nota: este ejemplo puede no ser el mejor para este método pero demuestra el punto y el uso).

Answer 3

Use una etiqueta plural de estilo "... (s)", con un {@link} a la clase:

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

Esto se procesará como:

Devuelve un IdentityBank de Identity(s) con el sexo dado.

Es fácil y más natural de leer, y obvio y claro lo que está diciendo.

Deberías estar usando {@link} todas formas para las clases. Se ocupa del formato de estilo <code> y proporciona un enlace HTML a la clase real.

Puede codificar los "(s)" después del enlace, es decir, {@link Identity}(s) , lo que significa un uso completamente convencional de {@link} , pero habría un cambio de fuente a mitad de la palabra:

Devuelve un IdentityBank de Identity(s) (es) con el sexo dado.

que IMHO reduce la claridad y podría causar confusión.

Answer 4

^{Cuando vi el título de la pregunta, me pregunté: ¿cómo es posible que esto no se haya cerrado después de 5 minutos como "Basado principalmente en la opinión"? Pero creo que es una pregunta importante, y he estado agonizando demasiado por esto, hasta que llegué a la conclusión de que puede haber diferentes argumentos (objetivos, es decir, no basados ​​en opiniones) para las diferentes opciones. Mis dos centavos:}

Usando los nombres de clase Customer e Identity como ejemplos, hay diferentes opciones, que se representarán de la siguiente manera:

1. Todos los Customer tienen Identity s

   Tener la "s" en una fuente diferente disminuye la legibilidad. El plural equivocado de "identidad" es cuestionable.

2. Todos los Customer tienen Identities

   Esto puede verse bien a primera vista. Pero tiene un grave inconveniente: ¡es una práctica común añadir una s a los nombres de clase para las clases que contienen métodos de fábrica! Por ejemplo, una clase que contiene métodos de fábrica para los objetos del Customer , por convención, se llamaría Customers . Y un JavaDoc como este ...

   Puede crear Customer con los métodos en la clase Customers

   es claramente confuso: el enlace no conduce a la documentación que puede esperar del nombre en el que está haciendo clic.

3. La solución que generalmente aplico (y ya la utilicé anteriormente, al hablar del inconveniente del enfoque 2.):

   Todos los objetos del Customer tienen objetos de Identities .

   Sí, puede parecer un poco antinatural, pero considero que es la mejor compensación: el nombre Identities es legible, es obvio que es un nombre de clase y no es ambiguo que el nombre de la clase sea Identity .

Una nota al margen: usualmente inserto los nombres como {@link ...} . Esto es conveniente debido a la finalización automática en Eclipse y porque puede simplificar significativamente la navegación a través de los JavaDocs resultantes. Recomiendo usar {@link ...} al menos la primera vez que aparezca un nombre de clase en un bloque de documentación. Para más apariciones, se puede utilizar <code>...</code> .