Bien communiquer au sein d’un projet est primordial pour sa réussite et passe notamment par une bonne compréhension du code par tous. Dans notre précédent article, nous avons commencé à voir comment bien nommer ses variables afin que votre code soit lisible et intelligible facilement, y compris pour des personnes découvrant le projet. Voici la suite de nos conseils et bonnes pratiques concernant la nomenclature de vos variables, constantes et fonctions.
Règle 3 : Normaliser le nom de chaque variable
Dans l’article précédent nous abordions l'importance de donner du sens à une variable afin de rendre le code clair. Il est tout aussi essentiel de normaliser le nom des variables et surtout de définir et s’accorder sur une convention commune à adopter pour le nommage. La mise en place de ces conventions permet :
de simplifier le choix du nom des variables puisque les règles fixent un cadre
de simplifier la communication en réunissant les développeurs puisque les termes employés sont les mêmes
Par exemple dans le code suivant :
les termes "genre" et "type" renvoient-ils bien à la même notion ? Peut-on vraiment comparer le genre du produit au type de produit de la commande ? Le mélange des langues ne facilite pas la compréhension de ce que la méthode est censée faire. L'utilisation d'un terme imprononçable pour le paramètre de type commande complexifie rapidement les échanges, en particulier à l’oral : "le problème provenait du productType de la cmdIdx4 qui ne renvoyait pas la valeur attendue"
Voici une version plus compréhensible de ce même code :
Dans le code revisité ci-dessus, la comparaison est plus évidente et les échanges plus simples : "le problème provenait du productType de la commande qui ne renvoyait pas la valeur attendue".
Comme précédemment, voici une liste d’erreurs communes à proscrire lorsque vous nommez vos variables :
- Donner à ses variables des noms imprononçables (par ex "private int pszqint;," "private Date genymdhms;") : travailler en équipe implique de pouvoir échanger de vive-voix. Il devient très difficile de parler d'un code qui contient des variables que l'on ne peut pas prononcer…
- Mélanger plusieurs langues dans un même nom (par ex "private int isUnElementDansTheList;") : les mélanges de langues favorisent le manque de cohérence dans le nommage des variables, ce qui peut les rendre plus difficiles à trouver dans le code, amène parfois à utiliser différents noms pour la même variable, et complexifie au final la tâche de nommer une variable. Privilégiez l'emploi systématique de l'anglais sauf pour les termes métier difficilement traduisibles.
- Multiplier les termes pour une même notion (par ex "genreProduit" et "typeProduit") : avoir des termes qui diffèrent pour une même notion complexifie d'un côté le choix du nom du variables et introduisent une ambiguïté. Parle-t-on de la même notion ? De notions différentes ? Sans parler des termes suffisamment génériques pour qu'ils puissent potentiellement être utilisés dans d'autres contexte pour une autre notion...
Règle 4 : Utiliser des noms de fonctions explicites
Les fonctions sont des opérations qui prennent pour paramètres un ensemble de champs et qui retournent ensuite un résultat, stocké en général dans une variable. Attribuer à chaque fonction un nom pertinent permet de comprendre ce que fait la fonction considérée et rend plus lisible les différentes étapes qui constituent un algorithme.
Ainsi, en reprenant l’exemple de l’article précédent, si nous prenons le code suivant :
Le nom de la fonction "getThem" n'apporte aucun éclairage sur ce que fait la fonction. Si l'utilisateur veut comprendre ce que fait la fonction "isSomething", il doit aller chercher dans le corps de la méthode "getThem" l’information nécessaire pour analyser son fonctionnement, ce qui lui fait perdre du temps inutilement.
Si l’on reprend ce même code mais avec cette fois-ci des noms de fonctions pertinents, cela donne par exemple :
Grâce aux astuces et bonnes pratiques énoncées lors de ces deux articles dédiés à la nomenclature, le code produit par votre équipe sera plus facilement compréhensible par tous et vous gagnerez en efficacité et en communication sur vos projets.
Et vous, quelles sont les bonnes pratiques que vous avez mis en place au sein de votre équipe pour le nommage de vos variables, fonctions,… ?
Comentarios