Dans un précédent article, nous avons exposé les principes fondamentaux que nous suivons et que nous avons formalisés dans une charte pour le développement backend.

Dans cet article, nous allons examiner en détail le sujet de la lisibilité du code et la collaboration avec les autres développeurs.

Lisibilité

Comme présenté lors de la première partie, notre priorité absolue est de produire du code fonctionnel et maintenable par d’autres développeurs.

Pour y parvenir, nous privilégions toujours la lisibilité du code plutôt que la performance, la brièveté ou d’autres aspects du code.

Toutefois, nous sommes conscients que certaines situations exigent des performances supérieures et dans ces cas, nous accordons une attention particulière à la documentation de nos choix.

Commentaires

En général, notre objectif est de créer du code autodocumenté, c’est-à-dire du code qui “parle de lui-même” et ne nécessite pas de commentaires. Nous cherchons donc à remplacer les commentaires par des noms de variables plus explicites ou en extrayant du code dans des fonctions plus parlantes.

On peut dire que nous considérons généralement qu’un commentaire est un signe d’échec : cela implique que le code ne parle pas suffisamment de lui-même.

Toutefois, il y a des situations où les commentaires sont nécessaires et appropriés. Par exemple, pour expliquer des règles métiers ou dans la docstring des fonctions faisant partie d’une API.

Il est important de noter que les commentaires de type TODO ou FIXME doivent obligatoirement être liés à un ticket pour éviter qu’ils ne soient oubliés et laissés dans le code pendant des années.

Uniformité dans le style utilisé

Nous pensons que la familiarité est une caractéristique clé de la lisibilité du code. Nous croyons que chaque développeur devrait se sentir à l’aise lorsqu’il lit le code écrit par ses collègues. Pour atteindre cet objectif, nous sommes conscients que nous devons produire un code uniforme, qui respecte les conventions adoptées par l’équipe, même si cela signifie que l’individualité de chacun est moins mise en avant.

Nous nous engageons donc à respecter les conventions (parfois implicites) établies par l’équipe. Si nous souhaitons modifier ces conventions, nous devons le faire d’un commun accord et établir un plan de migration réaliste. Nous faisons tout notre possible pour éviter que du code écrit selon d’anciennes conventions ne soit en circulation plus de quelques mois.

Cette approche s’applique aussi bien aux aspects purement stylistiques, tels que le respect de PEP8, qu’aux aspects plus techniques ou “philosophiques”. Par exemple, nous veillons à éviter que de nouvelles fonctionnalités utilisent leur propre version d’un algorithme métier simplement parce que l’auteur n’était pas satisfait de l’existant. Nous encourageons la migration de l’existant ou l’acceptation des conventions existantes.

Utilisation de Git

L’importance d’un bon message de commit dans le développement backend ne doit pas être sous-estimée. Chez Deepki, nous utilisons Git pour retracer l’historique des modifications apportées au code et collaborer lors du développement d’une fonctionnalité. Les messages et le contenu des commits sont essentiels dans deux contextes différents : les revues de code et le développement lui-même.

Pour les revues de code, les commits permettent d’isoler certaines modifications du code pour se concentrer dessus. Ainsi, la multiplication des commits et les messages techniques ne sont pas un problème dans ce contexte.

Cependant, lors du développement, un bon message de commit peut clarifier l’intention derrière une partie du code. Lorsqu’on fusionne une branche, on préférera donc fusionner (squash) tous les commits pour ne garder qu’un seul message décrivant le besoin auquel on a répondu.

Pour rédiger un message de commit pertinent, nous avons une astuce : imaginer une phrase qui commence par “when merged, this commit will…” et la suite de cette phrase est le message de commit. En suivant cette méthode, nous pouvons écrire des messages clairs qui décrivent l’intention derrière chaque modification.

Par exemple :

  • fix a display bug where the id was used instead of the name
  • let the user enter multiple references for their asset
  • speed up the export of invoices when a filter is applied

Collaboration avec les autres

Nous privilégions l’utilisation d’Open API pour une bonne coordination avec les développeurs front-end. Un contrat d’interface est convenu afin que chaque partie puisse avancer avant que l’implémentation ne soit terminée. Il est cependant accepté que ce contrat puisse être amené à changer en cours de développement.

Les responsables produit (PM, PO, chef de projet) sont informés de l’avancement le plus souvent possible, surtout en cas de changements.

Le pair programming est fortement valorisé et pratiqué autant que possible par les développeurs backend, mais il ne remplace pas le processus de relecture du code (code review) qui apporte un regard neuf et du recul à ce qui a été produit, en plus de permettre au reste de l’équipe de simplement se tenir informé.

En cas de désaccord lors de la relecture, un compromis est recherché auprès du reste de l’équipe. D’une manière générale, il est attendu de l’auteur qu’il soit réceptif aux commentaires et sache amender son code dans le sens suggéré par ses pairs.

Conclusion

Dans cet article, nous avons examiné l’importance de la lisibilité du code pour produire du code maintenable. Chez Deepki, nous sommes convaincus que la lisibilité est essentielle pour permettre une collaboration efficace et maintenir un code de qualité à long terme.