Garder une base de code propre avec un design applicatif canon, une couverture de test au top : mon appli est juste trop cool ! Sauf que lire (et juste lire) les fichiers sources pique un peu les yeux… est-ce si grave ? Pourquoi ai-je besoin de formater mon code ?

La vision de Bob

« Think of a well-written newspaper article. […] We would like a source file to be like a newspaper article. » Clean Code, Robert C. Martin
Dans sa métaphore de la presse écrite, il insiste sur cet aspect « well-written » dans le sens construit, ordonné, qui invite à la lecture.
Sa réflexion est puissante quand il ramène le propos sur l’intention. À l’aide de tabulations, de sauts de lignes et d’espaces, le développeur serait capable de donner un sens, une indication supplémentaire sur l’intention de la/des ligne(s) écrite(s).
Formater son code est-il donc un incontournable dans une équipe de développement ?

Du code par les humains … pour les humains !

Chose vraie : notre code sera lu, minifié, optimisé, « bytecodé » et consorts par un programme ou compilateur. Pourquoi donc se prendre la tête à formater son code ?
Chose étonnante : si l’on compare le temps mis par l’humain et la machine à lire du code versionné en informatique de gestion, la proportion de la machine est quasi nulle. En effet, ce code n’est lu par la machine que pendant le lancement du serveur de développement et une compilation CI/CD qui se quantifie en millisecondes. Au vu de la quarantaine d’heures hebdomadaires d’un développeur, le code source est quantitativement destiné à la lecture humaine.
Le rendre lisible et agréable à lire est, de ce fait, primordial !

Problématique inhérente à la question du premier paragraphe : qui dit équipe dit homogénéisation de la pratique. D’expérience, c’est un challenge intéressant de part la lubie du développeur à ne jamais utiliser le même IDE que son voisin.

Implémenter dans le workflow de développement une ou plusieurs étapes de vérification cross-IDE serait donc intéressant pour éviter les conflits de merge ou les commits d’un fichier entier alors que l’on en a modifié qu’une ligne.

Dans la description qui suit sera développée la mise en place d’un processus totalement automatisé ; processus qui pourra être décliné en fonction des habitudes de chacun.

Configuration

Pour l’exemple, focus sur une stack Java/Typescript.
Inutile de reprendre la théorie du Clean Code sur le “comment”. En revanche, en se basant sur l’extrait de code associé au chapitre, on se rend compte que la configuration minimale conseillée est … minimaliste.

Eclipse et IntelliJ, main dans la main

Les deux IDE ne partagent pas nativement des fichiers de configuration autour du formatage des sources. La façon la plus simple de construire cette alternative est de créer les fichiers sous Eclipse pour les importer ensuite sous IntelliJ :

• un fichier xml décrivant l’ensemble des règles pour des sources Java
• un fichier importorder pour la gestion des lignes d’import

Les gists ci-dessus matérialisent la configuration inspirée du Clean Code.

Pour les importer dans Eclipse :

Window > Java > Code Style > Formatter

• Import… > clean-code-2011.xml
• Active profile : Clean Code 2011

Window > Java > Code Style > Organize Imports

• Import… > example.importorder

Pour les importer dans IntelliJ, installer le plugin Eclipse Code Formatter. Les éléments de configuration principaux :

A ce stade, deux configurations supplémentaires pour automatiser le processus:

• Formater à l’enregistrement du fichier
• Formater au commit (configuration du VCS)

En bonus pour les allergiques de la souris :

• Ctrl+Alt+F pour Eclipse
• Ctrl+Alt+L pour IntelliJ

Pour les aficionados de la ligne de commande, pas de panique !

formatter-maven-plugin

Tout est dans son petit nom. Pour la configuration, c’est par ici.

• Vérifie que le projet est correctement formaté

mvn formatter:validate

• Formate le projet

mvn formatter:format

Ce plugin a le mérite de faire le travail même s’il ne donne pas beaucoup de flexibilité sur les fichiers impactés.

Prettier, notre sauveur Front

Projet datant de 2017, la librairie est simple et efficace :

• Configuration de l’ensemble des règles (exemple de configuration)

prettier --config .prettierrc.yaml

• Vérifie que le projet est correctement formaté

prettier --check

• Formate le projet

prettier --write

En comparaison avec le formatter-maven-plugin, prettier possède la possibilité d’indiquer le ou les fichiers souhaités. A noter également qu’un fork Java de Prettier est en cours de réalisation sous le projet JHipster.

Automatisation : Git à la rescousse

À l’instar de sa gestion incroyable des sources, Git est également un formidable outil d’automatisation grâce aux hooks.

Petit mémo pour configurer un hook :

• Configuration utilisateur du répertoire contenant les hooks

git config --global core.hooksPath /mon/super/chemin/hook

• Ou enrichissement au niveau application

cd .git/hooks

Voici un exemple de script pre-commit avec formatter-maven-plugin et prettier :

• Interdire le commit si le code java n’est pas formaté

MVN_POM=./pom.xml
if [ -s "$MVN_POM" ] ; then
   cat "$MVN_POM" | grep "formatter-maven-plugin" -q;
   if [ $? = 0 ]; then
     mvn formatter:validate
     if [ $? != 0 ]; then
       echo "Certains fichiers n’ont pas été formatés."
       exit 1
    fi
  fi
fi

• Formater les fichiers ts, html et scss modifiés dans le commit

FILES=$(git diff --cached --name-only --diff-filter=ACMR "*.ts" "*.html" "*.scss"| sed 's| |\\ |g')
[ -z "$FILES" ] && exit 0

PRETTIER=./node_modules/.bin/prettier

if [ -f "$PRETTIER" ]; then
  echo "$FILES" | xargs ./node_modules/.bin/prettier --write --print-width 120 --end-of-line lf
  echo "$FILES" | xargs git add
fi

Note : pour Prettier, une configuration alternative est possible avec les packages pretty-quick et husky :

npm install pretty-quick husky --save-dev

A ajouter dans le package.json :

{
   [...]
   "husky":{
      "hooks":{
         "pre-commit":"pretty-quick --staged"
      }
   }
}

Pour bénéficier des options de ce cas, il faut impérativement le fichier de configuration .prettierrc.

Tous ensemble pour un meilleur formatage !

Formater son code : oui oui et encore oui ! Faible coût de mise en place, confort de lecture et maintien de la cohérence des sources cross-IDE ; pas mal en termes de ROI.

Clean code donne une base minimale qui est à challenger et à améliorer. Le meilleur moyen d’appliquer du formatage de code reste que l’équipe s’approprie non seulement son utilité mais aussi les règles à appliquer.

L’automatisation a été un parti pris pour cet article. Cela permet simplement d’être exhaustif et de couvrir l’ensemble des possibilités pour une équipe. On peut s’arrêter à :

• diffuser les raccourcis clavier des IDE
• ajouter des plugins de live coding
• formater/bloquer systématiquement au commit (hook ou IDE)
• l’intégrer à la Definition Of Done/revue de code

Cela n’est aucunement une préconisation forte car cette ritualisation doit être dessinée par la pratique des membres d’une équipe.

Mahamoud Saïd Omar