Il est certain que la documentation améliore la qualité de tout logiciel. Nous pouvons le voir sur plusieurs projets réussis, tels que les plus utilisés dans l’industrie comme Java, Go, Apache Cassandra, etc. Mais la question est de savoir comment l’utiliser. Qu’est-ce qui devrait et ne devrait pas figurer sur la documentation ? Dans cet article, nous expliquerons ce que vous pourriez documenter en utilisant les ressources JavaDoc, ce qui vous facilitera la vie.
Javadoc
Javadoc est le générateur de documentation qui existe sur Java depuis son origine. En tant que développeur C/C++, vous connaissez peut-être les bases, comme mettre un commentaire sur une seule ligne et plusieurs lignes de mots. En utilisant Javadoc, vous pouvez faire encore plus. Javadoc nous permet d’utiliser des balises :
-
@author : vous pouvez définir qui a créé cette classe, ce package ou cette méthode
-
@since : spécifiez quand une fonctionnalité ou une méthode a été ajoutée
-
@version : la version actuelle
-
@param : étant donné une méthode ou un constructeur, les informations d’argument
-
@return : donné à une méthode une description de ce qui revient
-
@throws : qu’est-ce qui peut mal tourner lors de cet appel ? C’est une balise pour l’expliquer afin que l’utilisateur puisse l’éviter.
-
@see : pour obtenir plus d’informations sur une autre méthode.
Ces balises sont bénéfiques, principalement parce que le résultat final d’un JavaDoc est une page HTML, où vous pouvez voir ces informations sous forme de page de lien ou de description sur la page.
Cette session a présenté un bref aperçu de Javadoc. J’espère que je vous ai prouvé qu’il est plus puissant que la documentation C/C++. Vous pouvez utiliser ces balises pour mieux illustrer la documentation que Javadoc va générer en HTML. Allons faire du code. Commençons par le plus difficile – ce qu’il ne faut pas documenter.
Ce qu’il faut éviter dans une documentation
Pour moi, l’art de dire « non » est problématique. Cependant, nous devrions d’abord le mettre en pratique car plus de documentation signifie aussi plus de points à mettre à jour et à maintenir. Un autre point est l’effet de bruit; autant d’informations que vous placez, cela peut avoir un impact négatif, de sorte que l’utilisateur peut l’ignorer.
Évitez d’expliquer la syntaxe Java sur Javadoc ; s’il vous plaît, laissez-le être dans les tutoriels et articles Java. N’utilisez pas Javadoc pour expliquer la structure Java, les méthodes Java, etc. L’exemple de code ci-dessous est un exemple de ce que vous ne devriez pas faire :
/**
* This is a class
*/
public class Animal {
/**
* This is a field
*/
private String name;
/**
* This is a constructor
* @param name
*/
public Animal(String name) {
this.name = name;
}
/**
* This is a getter
* @return
*/
public String name() {
return name;
}
}
Éviter le bruit inutile sur la documentation est la première grande étape, la chose à propos de la valeur de cette information, alors dites-le. Passons à la session suivante, où nous pourrons l’explorer en profondeur.
Bonne documentation avec JavaDoc
Commençons par le non, la partie la plus difficile pour moi, parlons de ce que nous pouvons inclure sur le Javadoc. Dans un logiciel standard (un non-framework, une spécification ou tout autre outil d’expérience de développement), nous pourrions avoir deux bonnes options :
-
Pourquoi : La raison de cette décision de code. Par exemple, une description de la décision et une explication.
-
Point de vue métier : Le domaine est ce qui compte pour les logiciels, mettre une explication pour rapprocher le code du langage ubiquitaire est toujours une bonne utilisation de JavaDoc.
Imaginons le scénario FIFA, où nous devons créer une équipe ; nous pouvons dire pourquoi nous utilisons des records et certaines règles et validations autour du championnat de la FIFA. Comme vous pouvez le voir, toutes les méthodes n’ont pas de documentation ; c’est bon. S’il vous plaît, choisissez soigneusement ce que vous placez dans la documentation et où attirer l’attention de l’utilisateur.
public record Team(String name, List<Player> players) {
private static final int TEAM_SIZE = 11;
/**
* Once, we don't change the team during the championship, we'll create using record to make it immutable.
*
* @param name the team's name that is valid to FIFA
* @param players the players of the time that should not be higher the eleven.
* @throws NullPointerException when name or players are null
* @throws IllegalArgumentException when it has more than eleven players
* @deprecated please use {@link Team#of(String)} instead
*/
public Team{
Objects.requireNonNull(name, "name is required");
Objects.requireNonNull(players, "players is required");
}
/**
* Create an empty team
* @param name the team's name.
* @return a {@link Team} instance
*/
public static Team of(String name) {
return new Team(Objects.requireNonNull(name, "name is required")
, new ArrayList<>());
}
@Override
public List<Player> players() {
return Collections.unmodifiableList(players);
}
/**
* Add a new {@link Player} on the team
* @param player the player
* @throws NullPointerException when player is null
* @throws OverTeamException when it has more than eleven players.
*/
public void add(Player player) {
Objects.requireNonNull(player, "player is required");
if(this.players.size() == TEAM_SIZE) {
throw new OverTeamException("We don't support one more player");
}
this.players.add(player);
}
public boolean isEmpty() {
return this.players.isEmpty();
}
public int score() {
return players.stream().mapToInt(Player::score)
.sum();
}
}
Cette vidéo apporte plusieurs sujets pour augmenter votre documentation Java par JavaDoc :d