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.
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");
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 :
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: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.
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. #ViacheslavQue lire d'autre : |
---|
GO TO FULL VERSION