Qu’est-ce que le code propre ?

Le code propre est un code écrit non seulement pour compiler et s’exécuter, mais aussi pour que d’autres développeurs puissent en comprendre l’intention et le modifier, l’étendre et le vérifier ultérieurement en toute sécurité. Ce n’est pas un concept défini par une norme internationale stricte ou un score unique. Il s’agit plutôt d’un terme pratique qui englobe des objectifs de qualité tels que la lisibilité, la compréhensibilité, la maintenabilité, la cohérence et la sécurité des modifications. google.github.io↗

Au premier abord, il est facile de le considérer comme du code simplement « bien présenté ». En pratique, les moments importants surviennent après la première écriture du code : lorsqu’il faut corriger une fonctionnalité, trouver un bug, ajouter une exigence ou relire le travail d’un collègue. Le code propre vise avant tout à réduire le temps nécessaire et la probabilité d’erreurs dans ces situations. L’essentiel n’est donc pas de mémoriser certaines techniques de syntaxe, mais de réfléchir à ce qu’un lecteur doit savoir et aux endroits où une modification aura un impact.

Que signifie exactement le code propre ?

Un logiciel n’est pas un document que l’on écrit une fois pour toutes. Le code existant est relu lorsqu’on ajoute un statut de commande, modifie une règle de tarification ou enquête sur une erreur. Le lecteur peut être le développeur d’origine, mais il s’agit souvent d’un autre membre de l’équipe ou de vous-même dans le futur. Le code propre désigne un état dans lequel ce lecteur peut comprendre relativement vite le rôle du code, ses entrées et sorties, ses conditions importantes et les points susceptibles d’être modifiés.

Ici, « propre » ne renvoie pas uniquement à un jugement esthétique. Par exemple, même un code bien formaté est risqué à modifier si ses noms sont ambigus, si plusieurs responsabilités sont mélangées dans une même fonction et s’il n’existe aucun moyen de le vérifier. À l’inverse, un code peut être meilleur du point de vue de la maintenance si son rôle est clair, s’il respecte les conventions de l’équipe et s’il possède des tests permettant de confirmer les modifications, même s’il n’utilise pas un style particulièrement distinctif. La revue de code examine non seulement le style, mais aussi la conception, la correction fonctionnelle, la complexité, les tests et la documentation. google.github.io↗

Le terme « code propre » a été largement popularisé par le livre Clean Code de Robert C. Martin, publié en 2008. Toutefois, les recommandations de cet ouvrage s’inscrivent dans le contexte de certains langages et de pratiques de développement orienté objet. Au lieu d’appliquer sans changement les règles d’un livre ou des règles connues à tous les langages et à toutes les tailles de programmes, il est plus pertinent de déterminer si elles résolvent un problème dans la base de code et l’équipe actuelles. www.informit.com↗

Pourquoi un code qui fonctionne ne suffit-il pas ?

Produire le résultat attendu pour les entrées actuelles est l’exigence la plus élémentaire d’un programme. Mais même une fonctionnalité correcte est difficile à gérer à long terme si elle se casse facilement lors de la prochaine modification. Par exemple, une longue fonction peut contenir le calcul d’une remise, des contrôles d’autorisation, le rendu de l’affichage et le stockage de données. Elle peut fonctionner aujourd’hui, mais une personne souhaitant modifier uniquement la politique de remise risque davantage d’affecter aussi la gestion des autorisations ou l’ordre de stockage.

Un code difficile à lire ne se limite pas à prendre plus de temps à lire. Sans confiance dans son intention, les développeurs peuvent copier une logique similaire, modifier une zone plus large que nécessaire ou recréer des règles déjà existantes. Les relecteurs ont également du mal à évaluer l’impact d’un changement. La maintenabilité est la propriété qui évite de bloquer les modifications futures, et le code propre se concentre sur l’amélioration de cette maintenabilité.

Personne ne peut toutefois éliminer à l’avance tous les coûts des changements futurs. Lorsque les exigences elles-mêmes sont complexes ou que des systèmes externes imposent de fortes contraintes, le code sera aussi complexe dans une certaine mesure. Le meilleur objectif n’est pas de prétendre que la réalité est simple, mais de distinguer la complexité évitable de celle qui est inévitable. Si une complexité est nécessaire, sa raison doit être rendue visible par la structure, les noms, les tests et la documentation.

Comment de bons noms révèlent-ils l’intention du code ?

Les noms sont les informations que les lecteurs rencontrent le plus souvent lorsqu’ils cherchent à comprendre un code pour la première fois. Des noms génériques tels que x, data, process et flag peuvent être familiers à leur auteur, mais ils n’indiquent pas aux autres ce qu’ils représentent. À l’inverse, des noms comme expiredCouponCount, isEligibleForRefund et calculateShippingFee communiquent relativement directement la finalité d’une valeur ou d’une opération. Des noms porteurs de sens permettent aussi de transférer dans le code lui-même des informations qui devraient autrement être expliquées dans des commentaires. google.github.io↗

Un bon nom est une question de précision, pas de longueur. Un concept largement compris dans une petite portée peut avoir un nom court, tandis qu’une valeur utilisée dans une portée plus large peut nécessiter davantage de contexte. Par exemple, l’indice de boucle i peut être compréhensible au sein d’une boucle très courte. Mais si la valeur de retour d’une fonction ou un champ d’objet s’appelle seulement result, il est difficile de savoir s’il représente un succès, un montant ou le résultat d’une requête.

Il est également utile de distinguer les verbes des noms. La lecture est généralement plus naturelle lorsque les fonctions ont des noms fondés sur des verbes qui révèlent ce qu’elles font, tandis que les valeurs et les objets ont des noms fondés sur des noms communs qui révèlent ce qu’ils sont. sendReceipt() est une action, tandis que receiptEmail est une donnée. Cependant, allonger un nom ne supprime pas automatiquement l’ambiguïté. handleUserData est plus long, mais il reste imprécis quant à ce qu’il traite.

// Example with unclear intent
if (a) {
  doIt(b);
}

// Example where the purpose of the condition and action is visible
if (isPaymentApproved) {
  sendOrderConfirmation(order);
}

Les noms du second exemple doivent tout de même être adaptés au contexte réel. L’objectif est de permettre aux lecteurs de comprendre la décision importante sans devoir chercher loin les définitions de a et de b. Par rapport à une structure dans laquelle des commentaires répètent ce que les noms expliquent déjà, le fait de rendre les noms et la composition du code explicites par eux-mêmes réduit le risque que l’explication devienne obsolète après une modification.

Dans quelle mesure faut-il découper les fonctions et la structure ?

Lorsqu’une fonction ou un module effectue trop de tâches, les lecteurs doivent garder simultanément plusieurs règles à l’esprit. Si la validation des entrées, le calcul, les appels externes, la gestion des erreurs et le formatage des résultats sont mêlés dans un même bloc, modifier une partie peut exiger de comprendre tout le flux. Séparer les étapes liées en unités nommées peut faciliter la lecture du flux général.

Par exemple, un processus de confirmation de commande peut être représenté par des étapes telles que validateOrder, calculateTotal, reserveInventory et createPayment, qui expriment le flux métier. Le but de cette séparation n’est pas d’augmenter le nombre de fonctions, mais de faciliter la lecture de la responsabilité et de l’ordre de chaque étape. Si une fonction extraite ne contient qu’une ligne et si son nom est moins clair que l’expression d’origine, il est difficile de conclure que cette extraction améliore la compréhension.

Un découpage excessif crée le problème inverse. Les lecteurs peuvent devoir naviguer entre de nombreux fichiers et des fonctions minces pour comprendre une seule action. Des abstractions telles que les interfaces ou les types ont l’avantage de masquer les détails d’implémentation, mais elles peuvent également masquer le contexte nécessaire. Il faut utiliser l’abstraction lorsqu’elle apporte un bénéfice clair, et non en partant du principe que « plus d’abstraction signifie toujours une meilleure conception ». google.github.io↗

La décision de découper peut donc être guidée par des questions comme celles-ci :

• Cette partie a-t-elle un rôle qui peut être expliqué indépendamment ?
• Son nom explique-t-il mieux l’intention que la lecture de son code interne ?
• La même règle est-elle répétée à plusieurs endroits, ce qui justifierait de la regrouper en un seul lieu ?
• Crée-t-elle une frontière telle que seule cette partie doit être examinée lors d’une modification ?
• Après la séparation, le suivi des appels rend-il au contraire le flux global moins clair ?

Ces questions ne produisent pas automatiquement une réponse. Elles attirent toutefois l’attention sur le coût réel de compréhension du code pour les lecteurs, plutôt que sur des règles superficielles telles que « les fonctions doivent être courtes ».

La simplicité signifie-t-elle avoir moins de fonctionnalités ?

Dans le code propre, la simplicité ne signifie pas renoncer à des fonctionnalités nécessaires. Elle consiste plutôt à éviter les structures inutiles, les points d’extension non utilisés et les détours difficiles à comprendre qui ne sont pas exigés par les besoins actuels. Si vous généralisez uniquement sur la base de suppositions concernant les besoins futurs, les lecteurs actuels doivent comprendre des cas qui n’existent pas encore.

Par exemple, construire à l’avance un système de plug-ins multicouche pour une petite fonctionnalité qui ne propose qu’un seul moyen de paiement peut laisser de la place à de futures extensions. Mais cela augmente aussi immédiatement les chemins de code, la configuration et les combinaisons à tester. À l’inverse, si l’ajout de moyens de paiement est déjà confirmé et que leurs règles diffèrent fortement, créer une frontière commune peut réduire les modifications futures. Aucun de ces choix n’est systématiquement meilleur à l’avance.

La simplicité ne signifie pas non plus « le moins de lignes de code ». Compresser plusieurs conditions et transformations sur une seule ligne peut sembler astucieux à l’auteur, mais la personne qui le modifie doit interpréter les priorités et les exceptions. À l’inverse, utiliser des valeurs intermédiaires bien nommées et séparer les conditions peut augmenter le nombre de lignes tout en simplifiant le raisonnement. Les recommandations de revue de code soulignent également que les futurs développeurs doivent pouvoir lire, comprendre et modifier le code. google.github.io↗

En pratique, il est utile de considérer ensemble deux formes de simplicité. La première est la simplicité de l’implémentation elle-même : y a-t-il peu d’états, de branches, de dépendances et de duplications inutiles ? La seconde est la simplicité d’utilisation et de modification : les appelants peuvent-ils l’utiliser correctement facilement, et le lieu à modifier lors d’un changement de règle est-il clair ? Un choix qui simplifie l’usage externe peut parfois être préférable même si les mécanismes internes sont un peu plus complexes.

Pourquoi un style cohérent est-il nécessaire, et pourquoi ne suffit-il pas ?

Lorsque l’indentation, les retours à la ligne, l’organisation des fichiers et les conventions de nommage varient tous, les lecteurs doivent interpréter le format à chaque fois. L’utilisation cohérente d’un style convenu par l’équipe peut réduire l’attention consacrée aux différences superficielles du code. Les outils qui vérifient mécaniquement les règles, tels que les formateurs automatiques et les linters, peuvent être particulièrement utiles pour ce travail répétitif.

Toutefois, le seul respect du style ne rend pas le code propre. Même si chaque nom suit la même convention, les rôles peuvent rester ambigus ; même si les longueurs de ligne sont correctes, la conception peut rester excessivement enchevêtrée. L’évaluation de la qualité du code considère que la conception, la fonctionnalité, la complexité, les tests et la documentation doivent être pris en compte en plus du style. google.github.io↗

Lors de l’application de règles de style, respecter les conventions existantes de l’équipe est généralement pragmatique. Essayer une notation préférée dans un seul nouveau fichier peut sembler mineur, mais cela peut affaiblir la cohérence à l’échelle du projet. Inversement, une convention existante peut être discutée et modifiée si une amélioration accroît significativement la clarté. Ce qui importe n’est pas de rivaliser sur l’élégance d’une règle, mais de savoir si l’équipe peut lire et modifier le code de manière cohérente.

La revue de code exige aussi de distinguer les différences mineures de préférence des problèmes qui affectent la maintenabilité. Exiger la perfection à chaque modification peut ralentir l’amélioration elle-même. Si une modification améliore globalement la maintenabilité, la lisibilité et la compréhensibilité, l’accepter de manière progressive peut être plus réaliste. google.github.io↗

Quel est le lien entre les tests et le code propre ?

Les tests sont des moyens exécutables de vérifier les comportements promis par le code. Ici, une promesse désigne un comportement observable tel que « seules les commandes valides sont payées », « une commande déjà annulée n’est pas annulée une seconde fois » ou « le montant indiqué est déduit lorsque les conditions de remise sont remplies ». Les tests offrent une base pour vérifier qu’un comportement critique n’a pas été rompu après une modification.

Si le code propre est considéré uniquement comme du code qui a une belle apparence, les tests peuvent sembler distincts. Mais selon une définition qui inclut la sécurité des modifications, ils sont essentiels. Lors d’un nettoyage structurel, il faut pouvoir confirmer que le comportement externe a été préservé ; et lors de l’ajout d’une nouvelle règle, il faut vérifier que les anciennes règles n’ont pas été rompues accidentellement. Un code maintenable doit comporter des tests qui vérifient la logique centrale et les comportements promis, et qui aident à identifier la cause des défaillances. google.github.io↗

Le seul fait d’avoir beaucoup de tests ne garantit pas la qualité. Des tests trop étroitement couplés à un ordre interne mineur peuvent rendre difficiles même des améliorations structurelles légitimes. À l’inverse, des tests qui omettent des conditions limites importantes et des règles métier peuvent ne pas contribuer suffisamment à la sécurité des modifications, même s’ils sont nombreux. Les noms des tests et la structure arrange-act-assert doivent également être rédigés clairement afin que les lecteurs sachent ce qui est garanti.

Par exemple, si une logique calcule une période d’éligibilité au remboursement, il est plus pertinent de tester les limites de la règle réelle — comme la date limite elle-même, l’instant juste après cette date et une entrée manquante — que de vérifier seulement des dates ordinaires. Les cas à tester dépendent des exigences du produit et du risque. L’essentiel est que les tests communiquent non seulement que « du code existe », mais aussi « quel comportement doit continuer à être préservé ».

Quand les commentaires et la documentation sont-ils nécessaires ?

Les commentaires ne sont pas mauvais. Ils sont particulièrement utiles lorsqu’ils transmettent un contexte que le code exprime difficilement. Par exemple, les noms seuls peuvent ne pas suffire à indiquer un contournement d’un comportement anormal dans un service externe, des contraintes légales ou contractuelles, un choix fondé sur des mesures de performance, ou la raison d’un code temporaire de compatibilité qui sera supprimé après une date donnée. Ces informations aident les futurs responsables de la maintenance à comprendre pourquoi ils ne doivent pas le remplacer par une approche plus simple. google.github.io↗

À l’inverse, les commentaires qui se contentent de traduire ce que le code dit déjà peuvent se désynchroniser du code au fil du temps. Un commentaire indiquant « incrémenter le compteur de 1 » à côté de count = count + 1 n’apporte aucune information nouvelle. Dans ce cas, un meilleur nom ou une structure plus directe peut être prioritaire. Plus les commentaires deviennent longs, plus il vaut la peine de vérifier s’ils signalent une intention de code peu claire.

L’emplacement approprié de la documentation peut également varier. Une raison locale dans une fonction peut convenir à un commentaire placé à proximité. Des règles d’utilisation, des méthodes de configuration et des conditions de compatibilité partagées entre plusieurs modules peuvent être plus faciles à trouver dans une documentation distincte ou dans des descriptions d’interfaces. Quel que soit son emplacement, l’important est de fournir aux lecteurs le contexte nécessaire à la prise de décision et de le mettre à jour avec le code lorsqu’il évolue.

En quoi le code propre, le refactoring et le style de codage diffèrent-ils ?

Ces trois termes sont souvent mentionnés ensemble, mais ils ont des rôles différents. Le code propre est un état de qualité ou une perspective visant un code facile à comprendre et à modifier. Le refactoring est l’activité qui consiste à améliorer la structure interne tout en préservant le comportement observable de l’extérieur. Le style de codage est une convention d’expression du code, telle que l’indentation, la notation des noms et les espaces.

Le refactoring est une manière de créer ou de maintenir du code propre. Par exemple, des calculs de prix dupliqués peuvent être regroupés en un seul endroit, des noms ambigus peuvent être modifiés et des conditions peuvent être organisées en unités plus faciles à comprendre. Mais les changements structurels réalisés sans vérifier la préservation du comportement peuvent être risqués ; les tests et la revue sont donc importants.

Le style réduit les frictions de collaboration, mais il ne résout pas automatiquement les problèmes de conception. Inversement, un code clair avec une structure qui fonctionne n’est pas automatiquement mauvais simplement parce que son style diffère légèrement. Comprendre cette distinction évite de donner le même poids, en revue, aux problèmes de formatage et aux véritables risques de maintenance. google.github.io↗

Que doit-on privilégier en présence de contraintes de performance et de sécurité ?

L’accent mis par le code propre sur la simplicité et la clarté ne signifie pas qu’il faille sacrifier les performances, la sécurité, la compatibilité ou la fiabilité opérationnelle. Par exemple, un cache requis pour les performances, des étapes de validation requises pour la sécurité ou une gestion de compatibilité avec un ancien système externe peuvent rendre le code plus complexe. Si cette complexité repose sur des exigences réelles et des résultats de mesure, elle peut être plus appropriée qu’une alternative qui paraît seulement plus simple.

L’attitude importante dans cette situation n’est pas de cacher la complexité. Les contraintes, les comportements qui doivent être garantis et les raisons de ne pas utiliser une implémentation conventionnelle peuvent être rendus visibles par les noms, la structure, les tests et les commentaires nécessaires. Le principe consistant à privilégier les faits et les données techniques plutôt que les préférences personnelles s’applique à ces décisions. google.github.io↗

Par exemple, si une implémentation facile à lire ne satisfait pas les exigences de temps de réponse dans l’environnement de production réel, il est justifié de choisir une implémentation plus complexe. Cependant, il n’est pas souhaitable non plus de rendre tout le code complexe sous le seul prétexte que c’est « pour les performances ». Après avoir mesuré le problème et confirmé les exigences, il faut comparer les coûts comme les bénéfices de la complexité.

Il en va de même pour la sécurité. Des étapes comme la validation des entrées, les contrôles d’autorisation et la gestion des erreurs peuvent allonger le flux de code. Cela ne signifie pas qu’elles puissent être supprimées pour raccourcir le code. Une bonne structure place ces étapes nécessaires là où elles sont faciles à repérer et aide à éviter que des règles sensibles soient dispersées arbitrairement dans la base de code.

Quelles sont les idées reçues courantes sur le code propre ?

La première est l’idée reçue selon laquelle « plus court est toujours mieux ». Les fonctions courtes et les expressions concises peuvent aider, mais le nombre de lignes n’est pas le critère. Un découpage et une abstraction excessifs peuvent allonger les chemins d’appel et masquer le contexte. Au lieu de demander si le code est devenu plus court, demandez-vous si les lecteurs peuvent comprendre plus facilement le flux principal et ses raisons. google.github.io↗

La deuxième est l’idée reçue selon laquelle « moins de commentaires est toujours mieux ». L’idée d’exprimer par les noms et la structure ce que le code peut expliquer de lui-même ne signifie pas supprimer des informations de contexte utiles. En particulier, les raisons de certains choix et les contraintes externes peuvent devoir rester dans des commentaires ou dans la documentation. Les bons commentaires ne répètent pas le code ; ils fournissent un contexte difficile à connaître à partir du seul code. google.github.io↗

La troisième est l’idée reçue selon laquelle « le code n’est bon que s’il respecte toutes les règles ». Les recommandations sont des outils de jugement, et non un code juridique applicable à toutes les situations. Les priorités varient selon les caractéristiques du langage, les conventions de projet existantes, les exigences de performance et de sécurité, ainsi que l’expérience de l’équipe. Il est plus important de vérifier si l’application d’une règle rend réellement le code plus clair.

La quatrième est l’idée reçue selon laquelle « la conception doit être parfaite dès le début ». Les exigences changent, et certaines informations ne peuvent pas être connues initialement. Au lieu de retarder les changements en recherchant uniquement la perfection, il est plus réaliste de continuer à apporter de petites améliorations qui rendent le système actuel globalement plus facile à lire et à maintenir. google.github.io↗

Comment évaluer le code propre en pratique ?

Il est difficile de porter un jugement à l’aide d’une checklist absolue seulement, mais plusieurs questions peuvent être posées face à une modification. Demandez-vous d’abord si une personne qui voit le code pour la première fois peut en expliquer l’objectif principal. Ensuite, lors du changement d’une règle, vérifiez si l’endroit à modifier est relativement clair ou si des zones sans rapport doivent également être changées. Enfin, confirmez qu’il existe des tests ou des méthodes de revue permettant de vérifier le comportement central après la modification.

Voici des questions pratiques à utiliser lors de l’écriture ou de la revue d’une fonctionnalité :

• Peut-on comprendre approximativement le rôle d’une valeur, d’une fonction ou d’un module à partir de son seul nom ?
• Une fonction mélange-t-elle inutilement différentes règles métier ou opérations externes ?
• La même règle importante est-elle copiée à plusieurs endroits ?
• Le code respecte-t-il naturellement les conventions de l’équipe pour le nommage, le formatage et l’organisation des fichiers ?
• Les raisons des choix ou les contraintes que le code ne peut pas exprimer ont-elles été consignées lorsque nécessaire ?
• Existe-t-il un moyen de vérifier le comportement central et les conditions limites risquées ?
• La simplification a-t-elle négligé des exigences de performance, de sécurité ou de compatibilité ?
• L’abstraction ou la séparation réduit-elle réellement le coût de compréhension, ou allonge-t-elle seulement le chemin que les lecteurs doivent suivre ?

Vous n’avez pas besoin de répondre immédiatement à toutes ces questions. Essayer de résoudre tous les problèmes de conception dans une petite modification peut bloquer la revue. Il est pragmatique de corriger d’abord les problèmes à fort impact et d’orienter le reste dans une meilleure direction lors de modifications ultérieures. L’objectif de la revue de code peut aussi être l’amélioration continue de la maintenabilité, de la lisibilité et de la compréhensibilité du système, plutôt que la production d’un code parfait. google.github.io↗

Conclusion : le code propre est une qualité pour le changement, pas un format figé

Le code propre ne désigne pas seulement une liste de règles issues d’un livre particulier ou un formatage soigné. C’est une perspective de qualité qui rend l’intention du code visible dans les noms et la structure, réduit la complexité inutile, permet une lecture cohérente au sein d’une équipe et rend possible la vérification du comportement après les modifications. Les commentaires servent à transmettre le contexte, les tests soutiennent la sécurité des modifications et les abstractions sont utilisées lorsqu’elles facilitent réellement la compréhension et le changement.

La forme d’un bon code peut varier d’un projet à l’autre. Ce qui importe n’est pas de savoir s’il paraît court ou s’il suit une règle célèbre, mais si le prochain développeur peut le comprendre et le modifier correctement dans le cadre des exigences et contraintes actuelles. Améliorer continuellement les petits noms, les conditions, les tests et les structures selon cette perspective constitue le point de départ pratique du code propre. google.github.io↗google.github.io↗