<p> Dans Javadocs, comment dois-je écrire des formes plurielles d’objets singuliers en <code> tags?</code> </p>

Question

J'ai une classe nommée Identity . Dans mes commentaires javadoc, je le compare au pluriel. Je peux penser à deux solutions: changer la référence en <code>Identities</code> ou <code>Identity</code> s. Aucune de ces solutions ne semble correcte et je me demande s'il existe une meilleure solution.

Voici un exemple pour plus de clarté:

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

ou

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

Answer 1

Il semble que il ya deux choses que vous voulez faire ici: utiliser une bonne grammaire, mais aussi d'utiliser la traduction littérale, mot à mot les noms de vos classes, de sorte que les utilisateurs de votre javadoc peut regarder vers le haut.

Une chose que vous pouvez faire lorsque vous travaillez avec les pluriels est d'utiliser l'expression "X instances". Donc, à l'aide de votre exemple, vous pourriez mettre:

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

Si vous devez spécifier un pluriel d'un type de valeur (qui n'ont pas d'instances de soi), vous pouvez utiliser "les valeurs de X". Par exemple, vous pourriez dire "Renvoie une liste de valeurs int". D'autres noms acceptables pourrait être "dossiers", "notes", "entrées", "avis", ou, comme @Marco13 mentionné, "objets".

Vous devriez éviter d'utiliser des termes qui entrent en collision avec un terme existant de l'art ou un nom de classe dans votre cadre, un système ou une application, sauf si vous utilisez ce terme car il est déjà utilisé. Par exemple, pour ne pas dire "renvoie une liste de dossiers", sauf si vous faites référence à littérale des fichiers dans un système de fichiers. De l'utiliser pour se référer à une entreprise de règles concept d'un fichier ajoute le risque de confusion. D'autres conditions à éviter pour cette raison, peut-être "bases de données", "tables" (à moins que se référant aux tables réelles dans une base de données ou une abstraction ou de représentation de ceux-ci), "pages", "formulaires", "feuilles", "pilotes", "ports", "windows", "listes", "tas", "piles", "applications", des "exceptions" (sauf s'ils sont Throwable), "pins", et "bus".

De même, toute raisonnable nom à tous est utile si elle correspond aux règles de gestion du code et est compréhensible. Vous pourriez faire de ce qui suit:

• Retourne un Quadrant de MapNode entrées
• Retourne un BalancedTree des dossiers des Employés

Answer 2

L'utilisation d'un "...(s)" style pluriel de l'étiquette, avec un {@link} de la classe:

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

Ce sera le rendu:

Retourne un IdentityBank de Identity(s) avec le sexe.

Il est facile et plus naturel de les lire, et il est évident et clair ce que vous dites.

Vous devriez être en utilisant {@link} de toute façon pour les classes. Il prend soin de <code> style de mise en forme, et fournit un lien HTML pour la classe réelle.

---

Vous pouvez coder le "(s)" après le lien, c'est à dire {@link Identity}(s), ce qui signifie une complètement l'usage classique de l' {@link}, mais il y aurait un changement de police à la mi-mot:

Retourne un IdentityBank de Identity(s) avec le sexe.

ce qui à mon humble avis, réduit la clarté et pourrait causer de la confusion.

Answer 3

^{Quand j'ai vu la question du titre, je me demandais: Comment cela peut-il ne pas avoir été fermé au bout de 5 minutes comme "Principalement par opinion"? Mais je pense que c'est une question importante, et j'ai été à l'agonie pour ce beaucoup trop, finalement, à venir à la conclusion qu'il peut y avoir différentes (objectif, c'est à dire pas d' opinion!) des arguments pour les différentes options - voici donc mes deux cents:}

L'utilisation de la classe des noms d' Customer et Identity à titre d'exemples, il y a différentes options, qui serait rendue comme suit:

1. Tous Customers Identitys

   Avoir le "s" dans une police différente diminue la lisibilité. Le mauvais pluriel de "l'Identité" est discutable.

2. Tous Customers ont Identities

   Cela peut sembler agréable au premier coup d'œil. Mais il a un inconvénient grave: C'est une pratique courante pour ajouter un s pour les noms de classe pour les classes qui contiennent des méthodes de fabrique! Par exemple, une classe qui contient des méthodes de fabrique pour Customer objets, par convention, être appelés Customers. Et une JavaDoc comme ça...:

   Vous pouvez créer Customers avec les méthodes de la Customers classe

   c'est clairement à confusion: Le lien n'est pas conduire à la documentation que vous pourriez vous attendre à partir du nom que vous cliquez.

3. La solution que j'ai l'habitude de l'appliquer (et je l'avais déjà utilisé ci-dessus, lorsque l'on parle de l'inconvénient de l'approche 2.) :

   Tous Customer des objets ont Identity objets.

   Oui, il peut sembler un peu contre nature, mais je le considère comme le meilleur compromis: Le nom de l' Identity est lisible, il est évident que c'est un nom de classe, et il est unambigous que le nom de la classe est - Identity.

---

Une note de côté: j'ai l'habitude d'insérer les noms de la {@link ...}. C'est pratique en raison de l'auto-complétion dans Eclipse, et parce qu'il peut considérablement simplifier la navigation grâce à la naissance de la documentation Javadoc. Je vous recommande d'utiliser {@link ...} au moins la première fois lorsqu'un nom de classe apparaît dans un bloc de documentation. Pour de plus amples apparences, <code>...</code> peut être utilisé.

Answer 4

D'habitude, je préfère la troisième option de Marco13s réponse (c - {@link …} avec un autre mot au pluriel comme "objets"), mais parfois l'utilisation d' {@linkplain …} est également une bonne alternative:

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

Ce serait rendue quelque chose comme ceci:

Retourne un IdentityBank d' identités avec le sexe.

De cette façon, vous savez qu'il ya certains de la classe qui gère les identités (et tu peux trouver en suivant le lien), mais il est clair (à partir de la minuscule de l'orthographe et de la mise en forme) que ce n'est pas le nom exact de la classe, contrairement au procès - IdentityBank.

(Remarque: Cet exemple peut être pas le meilleur pour cette méthode, mais il montre le point et de l'utilisation.)