Bonnes pratiques de développement d'un ticket

De manière générale, avoir un code "propre" permet de réaliser des évolutions / correction d'anomalie plus rapidement. Nous allons aborder quelques règles "de bon sens" en vue d'obtenir un code évolutif.

1. Préambule

Les prérequis sont les suivants :

• Avoir un environnement de développement complet (Eclipse, PostgreSQL, Notepad ++ (optionel), WinMerge (optionel), Apache, Git Bash, EclEmma).
• Avoir les accès au code sur un gestionnaire de version
• Avoir configuré son environnement et son projet

Avant de commencer son évolution / correction , il est nécessaire de suivre le processus suivant avec GIT (gestionnaire de version) :

• Une branche doit être créée, faisant référence au ticket en cours.
• Une Merge Request (MR) doit être créée à chaque création de branche et doit contenir la chaîne "Draft: " et être affectée à soi-même.

Remarque : Une MR ne doit plus avoir la chaîne "Draft: " avant toute relecture de code par un tiers.

Utiliser de préférence le workflow "Gitflow" pour se repérer facilement dans GIT.

Attention : Les points cités ci-dessous peuvent être à modifier / compléter par le référent technique lors de la détection de certaine pratique.

2. Au niveau du code (Java / Javascript)

• Ne pas formater le code de tout le fichier, mais seulement le code modifié / ajouté.
• Respecter la convention de nommage de google (https://github.com/google/styleguide)
• Ne pas modifier les portions de code non impactées par l’évolution / correction de l’anomalie.
• Avoir documenté son code suffisamment pour qu’une personne extérieure au périmètre puisse comprendre facilement et rapidement ce qui a été effectué :
  • Les méthodes / classes ajoutées doivent être documentés.
  • Si la modification d’une méthode entraîne une modification du comportement décrit dans sa documentation, alors modifier la documentation de cette méthode / classe.
  • Si un bloc de code / algorithme est complexe, ne pas hésiter à documenter son fonctionnement.
  • Si un commentaire permettrait au code d'être plus compréhensible => ne pas hésiter à le mettre.
  • La déclaration d'un commentaire "inline" (//) doit être espacé d'un espace du commentaire (exemple : // Mise à jour de ...)
• La documentation du code doit être la plus part du temps sous forme d'action, exemple "Vérification que ...", "Mise à jour ...", "Affectation de ...", "Récupération de ..." ...
• Des commentaires pour expliquer son code doivent être à minima être crées pour chaque portion de 5 lignes au minimum.
• Le nom des classes / variables / méthodes doivent être en CamelCase.
• Le nom du fichier Java doit être le même que le nom de la classe.
• Les noms des classes / variables / méthodes  doivent être cohérents avec leurs contenus.
• Ne pas ajouter d’import non utilisé dans les classes
• Vérifier que le contenu des variables a été vérifié comme étant non null avant de réaliser une condition sur celle-ci.
• Préférer l'utilisation de constante static plutôt que des données "hard codé" (en dure).
• Utiliser les constantes / méthodes / classes existantes (si au niveau fonctionnel cela est valide) plutôt qu'en recréer.
• En Java, lors de la comparaison de String, Long, Double ... utiliser la méthode "equals" plutôt que le "==".
• Ne pas avoir d'affichage dans la console du type console.log / System.out.println
• Tous les affichages utilisateurs (texte, label ....) doivent faire référence à une properties (exemple dans le fichier package_fr.properties).
• Le code modifié / ajouté doit être formaté.
• Vérifier que le code modifié / ajouté n'augmente pas le nombre d'avertissements existants de Sonar.
• Réutiliser au plus l'existant (ne pas réinventer la roue).
• Rester cohérent avec le fichier au niveau de la langue utilisée (si les variables sont en anglais dans un fichier, alors les mettre en anglais dans ce même fichier).
• Ne pas utiliser de méthodes dépréciées.
• Utiliser au maximum des variables constantes (final / const).
• Factoriser son code, et splitter les méthodes en plusieurs morceaux pour une meilleur compréhension et réutilisation.
• Pour les méthodes "utiles", les positionner dans une classe spécifique à cet effet. Exemple : UtilsCollection.
• Utiliser au maximum des variable "public static final" dans le cas d'une utilisation (possible) multiple dans différentes classes.
• Utiliser au maximum des variable "private static final" dans le cas d'une utilisation (possible) multiple dans la même classe.
• Vérifier que la méthode / variable créée n'est pas déjà existante dans une autre classe (réutilisation), ou qu'une méthode / variable similaire n'a pas déjà été positionnée dans une autre classe (rester cohérent avec l'existant). Cette classe peut ne contenir que des constantes ou des méthodes "utiles". Cela permet de réutiliser et factoriser au mieux le développement.
• Ne pas avoir créé de code mort. Si tel est le cas, supprimer ce code. Un code mort complexifie la relecture et la compréhension d'une récupération des sources à un instant T. Si besoin, copier en local le code mort (ou dans une branche spécifique en local ou en remote) dans le cas d'une réutilisation ultérieure, ou se référer à l'historique GIT pour une récupération du code supprimé.
• Ne pas avoir de code en commentaire. Si besoin, se référer à l'historique GIT pour récupérer du code supprimé. Si besoin, copier en local le code supprimé (ou dans une branche spécifique en local ou en remote) dans le cas d'une réutilisation ultérieure, ou se référer à l'historique GIT pour une récupération du code supprimé.
• Ne pas mettre à jour des fichiers non impacté par l'évolution (même si ce sont des commentaires). Un ticket ultérieur pourrait être créé à cet effet.
• En JavaScript, mettre des ";" à chaque fin d'instruction ou le ";" est possible.

3. Tester son développement

Avant tout push du contenu de l’évolution / correction dans un gestionnaire de version, il est indispensable de tester sa modification de code au travers de tests fonctionnels (via le navigateur) et de tests unitaires (TU). Il est également important de tester les parties qui auraient pu être impactées à cause des modifications réalisées.

Exemple :
Si l’évolution consiste à griser un bouton lorsqu’il n’y a pas de document présent dans le tableau X, alors il convient de réaliser les tests suivants :

• Ajouter un document dans le tableau X et vérifier que le bouton est non grisé.
• Supprimer le document dans le tableau X et vérifier que le bouton est grisé.
• Ajouter un document dans le tableau X et rafraîchir la page. Vérifier que le bouton est non grisé.
• Supprimer le document dans le tableau et rafraîchir la page. Vérifier que le bouton est grisé.
• Ajouter un document dans le tableau X. Cliquer sur le bouton non grisé afin de vérifier que le fonctionnement initial n’a pas été altéré.
• Supprimer le document dans le tableau X et vérifier. Cliquer sur le bouton grisé afin de vérifier que le fonctionnement initial n’a pas été altéré.
• Ajouter un document dans le tableau X et rafraîchir la page. Cliquer sur le bouton non grisé afin de vérifier que le fonctionnement initial n’a pas été altéré.
• Supprimer le document dans le tableau X et rafraîchir la page. Cliquer sur le bouton grisé afin de vérifier que le fonctionnement initial n’a pas été altéré.

4. Tests unitaires

Il est nécessaire d'avoir des tests unitaires (TU) correspondant à l'évolution. Il est indispensable d'effectuer les recommandations suivantes :

• Mettre à jour les tests unitaires existants ET correspondant à l'évolution / correction effectuée.
• Ajouter les tests unitaires liés au développement effectué.
• La couverture minimale du code testé par un TU doit être de 70 % (utiliser l'outil EclEmma).
• Tous les TU existants doivent continuer de fonctionner après les modifications.

5. Au niveau de GIT (gestionnaire de version)

5.1 Recommandations

• Il est recommandé de commiter son code chaque soir (au minimum).
• Un commit peut comprendre à lui seul la correction du ticket (utiliser si nécessaire la commande suivante : git rebase origin/develop -i).
• Il peut y avoir plusieurs commits pour une évolution.
• Le nom des commits doit être parlant et dans la même langue que les commits précédents.
• Le nom des commits doit respecter la même nomenclature que les commits précédents.
• Utiliser le rebase pour mettre régulièrement sa branche à jour par rapport à la branche develop.
• Récupérer régulièrement le code de la branche de travail afin d'éviter de gros conflits.
• Ne pas utiliser de merge dans sa branche au lieu de rebase.
• Le nom du commit doit être sous la forme d'une action. Exemple "Mise à jour ....", "Récupération de ...", "Correction de ...", "Ajout de ...." ...
• Avoir un fichier de configuration (.gitconfig) complet.
• Si un dossier doit être créé, mais qu'il est vide, alors créer un fichier .gitkeep vide dans ce dossier. Lors du remplissage du dossier, supprimer le fichier .gitkeep.

5.2 Exemple de nomenclature

5.2.1 Nomenclature du nom des branches

Lors de la création des branches, il est nécessaire de garder une certaine cohérence avec le nom des branches précédentes afin de pouvoir les rechercher / traiter plus facilement :

• Une branche corrigeant une anomalie : fix/<NUMERO-TICKET>-<DESCRIPTION-DU-TICKET>
• Une branche pour une nouvelle fonctionnalité : feature/<NUMERO-TICKET>-<DESCRIPTION-TICKET>
• Une branche pour des tests : test/<NUMERO-TICKET>-<DESCRIPTION-TICKET>
• Le nom de la branche doit être en minuscule, sans accent, sans point et sans espace (le tiret "-" est utilisé pour séparer les mots).

5.2.3 Nomenclature du nom des commits

Lors de la création de commit, il est nécessaire de garder une certaine cohérence avec le nom des commits précédents afin de pouvoir les rechercher / traiter plus facilement.

Le commit doit avoir le nom suivant : "[<NUMERO-TICKET>] - <TYPE-DE-BRANCHE> - <DESCRIPTION-DU-COMMIT>"

La variable "<TYPE-DE-BRANCHE>" peut avoir les valeurs suivantes : FEATURE, FIX ou TEST

5.2.3 Nomenclature du nom d'une Merge Request

La Merge Request (MR) doit porter le même nom que la branche à associer.