Dans le précédent chapitre, nous avons présenté les avantages de bénéficier d’une documentation de qualité pour un code évolutif et maintenable, en particulier dans un contexte de travail en équipe.
Dans ce chapitre, je vous propose de rentrer dans le vif du sujet : comment écrire la documentation d’un projet de code ?
Organisez vos fichiers
Les mauvaises pratiques
Quand on travaille sur des projets de taille limitée, personnels ou professionnels, on est tous tentés de mettre tous les fichiers à la racine du projet afin de gagner du temps. Mais dès que le projet prendra de l'ampleur, le manque de structure deviendra un réel problème pour la maintenance du code.
Imaginez les millions de lignes de code nécessaires à l’écriture du noyau de votre distribution Linux préférée, placées dans quelques fichiers à la racine de l’arborescence. Ça serait un fouillis impossible à travailler !
En effet, les projets s’étoffent avec des bibliothèques externes, s’enrichissent avec de nouvelles fonctionnalités qui deviennent des modules et les dépendances de votre code se diversifient... Il faut donc organiser vos fichiers de code.
Comment organiser vos fichiers ?
Il n’y a pas de solution parfaite, seulement des conventions d’équipe ou des organisations qui vous permettent de travailler plus efficacement.
Pour ceux qui ne seraient pas (encore) convaincus, jetez un coup d’œil à :
la structure d’un projet Android qui contient les sources, les ressources, les tests et la configuration. Les différentes fonctionnalités sont organisées en modules spécifiques et autodocumentées. Par ailleurs, le code source Java est cloisonné du reste des ressources ;
la structure d’un projet Symfony qui sépare le code source, la configuration, les tests, les bibliothèques tierces et les ressources publiques tout en respectant le modèle MVC. Elle permet donc de séparer le modèle de données, la vue (l’interface) et le contrôleur (la logique).
Ces exemples nous montrent quelques implémentations propres. Vous pouvez vous en inspirer, mais je vous conseille au minimum les points suivants :
pour améliorer la lisibilité et l’évolutivité de votre code, placez vos fonctionnalités distinctes au sein d’ensembles distincts (comme des modules, des fichiers différents, etc.) ;
pour plus de clarté, séparez le code source des dépendances que vous utilisez ;
les tests pourront être placés dans un répertoire dédié aux tests ;
je vous conseille également de séparer physiquement les différents environnements (prod, dev, etc. ).
Commentez votre code
Utilisez des commentaires… avec parcimonie
Ils sont à la fois un puissant moyen pour clarifier un point particulier comme une technique spécifique utilisée dans une fonction, pour mettre en œuvre votre outil automatique de documentation (comme Javadoc) ou bien pour placer des avertissements dans votre code.
Écrivez du code autodocumenté
En d’autres termes, un bon code est sa propre documentation. Lorsque vous êtes sur le point d’ajouter un commentaire, demandez-vous : « Comment puis-je améliorer le code de sorte que les commentaires ne soient plus nécessaires ? ».
Améliorez le code, puis documentez-le pour le rendre encore plus clair.
Prenons cet exemple simpliste :
//Check if user's credentials allows him to connect
if ((user.login = request.getParameter("login")) && (user.password = request.getParameter("pass")) && (user.secretNumber = request.getParameter("secretNumber")
])) Mon conseil serait de le remplacer par ce code :
if (user.hasCredentials())Ensuite, nous pourrons implémenter la logique de vérification de l'authentification dans la méthode hasCredentials() et ce sera bien plus compréhensible.
Faites des commentaires utiles
Dans certains cas, même avec la meilleure volonté du monde, le code est difficilement explicite. Ça peut être le cas quand on manipule des expressions régulières, par exemple.
Prenez par exemple cette portion de code, qui traite des plaques d’immatriculation des voitures françaises :
// format matched DD-ddd-DD
Pattern frenchCarPlateMatcher = Pattern.compile([A-Z]{2}-\d{3}-[A-Z]{2});Le commentaire permet ici de faciliter la compréhension du format attendu. Cette démarche serait d’autant plus indispensable dans le cas d’expressions régulières beaucoup plus compliquées.
En plus de ça, comme nous l’avons vu avec Javadoc, de nombreux outils sont capables de générer de la documentation de manière automatique à partir de cartouches correctement implémentés.
Par exemple, pour une fonction, voilà les points que je trouve intéressants d’aborder dans un cartouche :
une description de la fonctionnalité ;
les paramètres à transmettre avec une description de leur rôle ;
le résultat attendu ;
la version ;
l’auteur ;
si la fonction est obsolète, il faut le spécifier et donner son remplaçant.
Pour illustrer ce point, je vais commenter une fonction simple qui permet de se connecter à une base de données.
/**
* Allows to connect to a postgreSQL database
*
* @param url string of the endpoint to connect to
* @param user string of the user to be connected with
* @param password string of the user
*
* @return void
* @author Francis
* @version 1.0
*/
public void databaseConnect(String url, String user, String password) {
try {
Class.forName('org.postgresql.Driver');
Connection conn = DriverManager.getConnection(url, user, password);
System.out.println('Connexion effective !');
}
catch (Exception e) {
e.printStackTrace();
}
}Enfin, parfois votre entreprise impose des normes de commentaires qui contiennent des aspects légaux, comme le copyright par exemple. Ces types de commentaires sont bénéfiques car ils participent au respect de la propriété privée. Ci-dessous un exemple :
// Copyright (C) 2020 by Fake Industries
// Released under the terms of the Creative Commons LicenceÉvitez les commentaires inutiles ❌
Les commentaires répétitifs
Prenons l’exemple du cartouche ou commentaire Javadoc suivant :
/**
* Function that draws a circle on the screen
*
* @param Circle
* @return void
*/
public void drawCircle(Circle circle) {
...
} Clairement, ici le commentaire est une pure répétition du code ; il n'est pas nécessaire de le mettre.
Les commentaires obsolètes
De plus, comme expliqué plus haut dans le cours, faites la chasse aux commentaires obsolètes. Au fur et à mesure du temps, ces commentaires deviennent douteux, induisent en erreur et polluent la lisibilité de votre code et donc sa maintenabilité et sa qualité.
Les commentaires incompréhensibles
Une autre bonne pratique que je vous conseille est la suivante : si, malgré tous les efforts possibles dans votre code, il vous semble toutefois indispensable d’écrire un commentaire, prenez le temps nécessaire pour le rendre intelligible.
Il n’y a rien de plus chronophage dans une équipe que d'être obligé de vous creuser la tête pour comprendre ce qu’un autre développeur a voulu dire. Encore pire, s’il faut aller chercher dans un autre module de code la signification du commentaire laissé là.
Regardez le code suivant :
public void loadAndWriteJsonFile(String url){
try
{
FileInputStream jsonFile = new FileInputStream(url);
String jsonString = IOUtils.toString(jsonFile, UTF-8);
JSONObject jsonObj = new JSONObject(jsonString);
sendRequest(jsonObj.getString(trademark),jsonObj.getString(owner));
}
catch(IOException e)
{
// No JSON files means default settings are loaded.
}
}Le commentaire laissé ici n’est vraiment pas explicite : on ne sait pas quelle fonction doit charger les réglages par défaut, ou bien encore si l’auteur n’a pas laissé ce commentaire pour y revenir plus tard.
Ici, il aurait fallu écrire une fonction qui charge les paramètres par défaut plutôt que de laisser ce commentaire. Je vous propose la correction suivante :
public void loadAndWriteJsonFile(String url){
try
{
FileInputStream jsonFile = new FileInputStream(url);
String jsonString = IOUtils.toString(jsonFile, UTF-8);
JSONObject jsonObj = new JSONObject(jsonString);
sendRequest(jsonObj.getString(trademark),jsonObj.getString(owner));
}
catch(IOException e)
{
loadDefaultSettings();
}
} Les commentaires de suivi des changements
Un autre cas de commentaires inutiles que je souhaite partager avec vous sont les commentaires relatifs au suivi des changements dans le code. On parle de change log en anglais.
Si vous travaillez sur du vieux code, vous pourrez trouver ce genre de commentaires qui étaient très utilisés quand les outils de versioning comme GitHub ou SVN n’étaient pas aussi répandus qu’aujourd’hui. De nos jours, il n’est plus nécessaire d’en faire usage.
Par exemple, il y a quelques années, il n’était pas rare de voir ce genre de commentaires au début d’un fichier :
/** Change log (from 17/02/2020)
* --------------------------
* 17/02/2020 : Add constructor to the class ;
* 15/02/2020 : Added the DAO class to the package ;
* 13/02/2020 : Change AddProduct() to AddProductToShappingCart() ;
* 13/02/2020 : Fixed bugs in addProduct() ;
*/ N'utilisez plus ce genre de commentaire, votre Git est là pour ça !
Les commentaires pour les fins de boucles
Pour terminer, je vous déconseille d’utiliser des commentaires pour marquer la fin de vos structures de contrôle comme dans le code classique du tri à bulles ci-dessous.
public static void triBulle(int tab[])
{
int lengthTab = tab.length;
boolean inversion;
do
{
invert = false;
for(int i=0;i<lengthTab - 1; i++)
{
if(tab[i]>tab[i+1])
{
swap(tab,i,i+1);
invert=true;
}//end if
}//end for
lengthTab--;
}//end do
while(invert);
} //end of functionMis à part le cas de fonctions particulièrement complexes, ce type de commentaires orphelins encombre inutilement le code et le rend donc illisible. Je vous encourage plutôt à chercher à réduire la complexité de vos fonctions et à en améliorer la lisibilité grâce aux bonnes pratiques que nous avons vues au chapitre 2.
Ces exemples ne sont pas exhaustifs mais dans ce chapitre, l’objectif était de vous éclairer sur le type de commentaires utiles et ceux qui ne méritent pas d’encombrer votre code.
En résumé
L’organisation rationnelle des fichiers d’un projet de code améliore sa lisibilité et son évolutivité. Séparer les différents environnements et les tests sont des bonnes pratiques que la majorité des frameworks récents proposent.
Un bon code est sa propre documentation. Lorsque vous êtes sur le point d’ajouter un commentaire, demandez-vous : « Comment puis-je améliorer le code de sorte que les commentaires ne soient plus nécessaires ? »
Dans ce chapitre, nous avons vu comment écrire la documentation de votre code.
Dans le prochain, je vous invite à voir en détail comment publier votre documentation en ligne et comment bien écrire vos commits.
