Commentaires en Java : tout n'est pas si simple

Introduction

Commentaires - il semblerait que cela pourrait être plus simple, et pourquoi écrire un article entier. Mais ce n'est pas si simple. Comme mon patron l'a dit, n'importe qui peut écrire du code, mais écrire un bon commentaire est difficile. La plupart des cours de langue commencent par le traditionnel Hello World. Même dans les didacticiels Oracle, dans la section « Mise en route », nous commençons par le message « Hello World ! » Application . Et dès les premières lignes de code, nous les voyons : les commentaires Java. Leur importance est également soulignée par le fait que dans un document aussi important que la Java Code Convention, les commentaires reçoivent une section distincte : Commentaires . Selon la documentation, les commentaires en Java sont divisés en deux types :

• commentaire d'implémentation (ou commentaire de code) ;
• documenter le commentaire.

Les commentaires de code sont utilisés pour décrire des lignes/blocs individuels, et les commentaires de documentation sont utilisés pour décrire la spécification du code (son interface) indépendamment de son implémentation. Les commentaires Java sont ignorés par le compilateur car ils ont du sens pour le développeur, pas pour l'utilisateur. Par conséquent, vous pouvez réduire la taille des classes compilées.

Commentaires sur le code Java

D'après le nom, il ressort clairement que ce commentaire concerne le code et doit refléter ses fonctionnalités. Les commentaires du code sont :

• Minuscules (c'est-à-dire décrits sur une seule ligne)

  // Строчный комментарий
  System.out.println("Hello, World!");




• Bloc (c'est-à-dire qu'ils sont décrits comme un bloc entier, car ils ne tiennent pas sur une seule ligne)

  /*
   * Блочный комментарий
   */
  System.out.println("Hello");

Une caractéristique intéressante d'un commentaire de bloc est que si nous le commençons par « /*- » (c'est-à-dire en ajoutant un signe moins après l'astérisque), alors le texte de ce commentaire de bloc ne sera pas formaté. Intéressant, mais avec l'aide de certains commentaires, vous pouvez donner quelques indices sur l'IDE. Par exemple, en utilisant les commentaires en ligne « //@formatter:on » et « //@formatter:off » dans l'EDI Eclipse, vous pouvez désactiver le formatage des sections de code. Vous devez utiliser les commentaires avec parcimonie et uniquement lorsque cela est nécessaire. Par exemple, vous pouvez lire un article sur ce sujet : « N’écrivez pas de commentaires sur le code ! » . Il existe un excellent livre intitulé Clean Code : Création, Analyse et Refactorisation de Robert Martin. Il comporte un chapitre distinct « Commentaires ». En épigraphe de ce chapitre, une citation tout aussi excellente : « Ne commentez pas le mauvais code, réécrivez-le » de Brian W. Kernighan et P. J. Plower. Ce chapitre peut être consulté sur Google Books . Le sens général peut être exprimé dans une citation de lui :

Chaque fois que vous écrivez un commentaire, vous grimacez et vous vous sentez comme un échec."

Il est clair qu’il n’y a pas de vérité absolue et des commentaires sont parfois nécessaires. Mais il existe toujours des options et il faut lutter contre les commentaires inutiles. Ce chapitre mentionne également des commentaires inhabituels, TODO :

// TODO: Добавить World
System.out.println("Hello, ");

Le point important est qu'ils peuvent être gérés d'une manière spéciale dans l'EDI. Par exemple, dans IDEA, ils sont collectés dans un onglet séparé, où vous pouvez les visualiser : Et un petit casse-tête avec un commentaire : La ligne « http://google.com » est une ligne valide à l'intérieur de la méthode, car http ici est en fait une balise, puis un commentaire. Souvent, de nombreux commentaires peuvent aller des commentaires de code aux commentaires de documentation, dont nous parlerons plus tard.

Commentaires pour la documentation

Les commentaires de la documentation décrivent l'API publique. L'API est l'interface de programmation d'applications, c'est-à-dire les classes et méthodes disponibles pour les autres développeurs pour effectuer des actions. Bref, ces commentaires doivent expliquer pourquoi telle ou telle classe et tel package ont été créés et ce que fait telle ou telle méthode. Vous pouvez également décrire les champs de classe si nécessaire. C'est exactement ce que nous voyons dans les info-bulles de nos IDE, qui sont présentées sous forme de JavaDoc. Par exemple: Si l’on approfondit cette méthode, on voit d’où vient ce texte : Encore une fois, consultez la Java Code Convention : Code Convention pour savoir comment formater correctement un JavaDoc . Ils sont un peu similaires aux commentaires bloqués, mais au lieu d'un astérisque (pas Astérix)), deux sont utilisés. Un exemple JavaDoc a été donné ci-dessus. Il ne sert à rien de décrire toutes les possibilités, puisque cela est déjà écrit dans la documentation officielle d'Oracle. Par conséquent, nous examinons tout ce dont nous avons besoin dans la documentation officielle JavaDoc , section "Descriptions des balises". Oracle propose même un didacticiel distinct sur ce sujet : Comment écrire des commentaires de document pour l'outil Javadoc . Les info-bulles de l'EDI sont sympas, mais ce sont en fait des documents pour une raison. Sur la base de ces commentaires JavaDoc, une documentation est générée. Il existe un utilitaire javadoc spécial pour cela . Comme nous pouvons le voir, ce tutoriel en parle. Une description de la façon de l'utiliser se trouve sur le site Web officiel d'Oracle pour JavaDoc . Pour voir par vous-même à quoi cela ressemble, vous pouvez créer un sous-répertoire dans le répertoire avec le nom du package, par exemple : test . Créez une classe simple avec des commentaires. Par exemple:

package test;

/**
 * This is a JavaDoc class comment
 */
public class JavaDocTest {

  /**
   * This is a JavaDoc public field comment
   */
  public static final String HELLO_MESSAGE = "Hello, World!";

  public static void main(String... args) {
    JavaDocTest.greetings();
  }

  /**
   * This is a JavaDoc public method comment
   */
  public static void greetings() {
    System.out.println(HELLO_MESSAGE);
  }
}

Après cela, nous pouvons exécuter la commande suivante à partir du répertoire qui contient notre répertoire de package : javadoc -d ./test test Après cela, nous verrons le processus de génération de documentation. Et puis nous pouvons ouvrir index.html pour voir le document généré. Vous verrez souvent de la documentation sur l'API publiée. Par exemple, l'API Spring Framework .

Conclusion

Comme nous pouvons le constater, une chose aussi simple en apparence que les commentaires s’avère en réalité beaucoup plus compliquée. Par conséquent, si vous consacrez du temps aux commentaires et les suivez, votre code sera meilleur et vous aurez plus de valeur en tant que programmeur. #Viacheslav