Code propre : Lutter contre la Dette Technique
Un code propre est évident pour les autres développeurs.
Il ne s'agit pas de créer des algorithmes complexes et sophistiqués. Des noms de variables mal choisis, des classes et méthodes surchargées, des "nombres magiques" — tous ces éléments rendent le code confus et difficile à comprendre. Un bon code est lisible, compréhensible et auto-explicatif, même pour quelqu'un qui ne l’a pas écrit.
Un code propre ne contient pas de doublons.
La duplication complique les changements futurs. Chaque fois que vous devez modifier un morceau de code dupliqué, vous devez vous souvenir de répliquer ce changement à chaque instance. Cela augmente inutilement la charge cognitive et ralentit le travail.
Un code propre est minimaliste.
Il doit contenir le strict nécessaire en termes de classes et d'éléments. Moins de code signifie moins de choses à comprendre et à maintenir, donc moins de bugs potentiels. Le code est une responsabilité — gardez-le concis et simple.
Les commentaires dans un code propre
Les commentaires jouent un rôle important dans la lisibilité et la compréhension d'un code, mais leur utilisation doit être judicieuse. Voici comment aborder les commentaires dans un code propre :
- Clarté et Contexte : Les commentaires doivent expliquer le pourquoi d'un choix plutôt que le quoi. Un bon code devrait être suffisamment clair pour que les développeurs comprennent la logique sans avoir à lire des commentaires détaillés. Les commentaires peuvent fournir un contexte précieux, comme la raison d'un algorithme particulier ou des détails sur une décision de conception.
- Éviter les Redondances : Évitez de commenter des éléments évidents ou de décrire ce que fait le code ligne par ligne. Par exemple, au lieu de commenter un code comme ci-dessous, il vaut mieux choisir des noms de variables explicites et rendre le code lisible.
x = x + 1 # Ajoute 1 à x
- Documentation des Fonctions : Utilisez des docstrings (commentaires en début de fonction) pour expliquer le but de la fonction, ses paramètres et ce qu’elle retourne. Cela aide à comprendre comment utiliser une fonction sans avoir à lire son code.
def add(a, b):
"""
Additionne deux nombres.
:param a: Premier nombre
:param b: Deuxième nombre
:return: Somme de a et b
"""
return a + b
- Mettre à Jour les Commentaires : Les commentaires doivent être mis à jour en même temps que le code. Des commentaires obsolètes peuvent induire en erreur et causer plus de confusion qu’ils n’en résolvent. Une bonne pratique est de revoir les commentaires lors de chaque refactoring.
- Sections et TODOs : Les commentaires peuvent être utilisés pour marquer des sections de code ou des tâches à accomplir (TODOs). Cependant, veillez à ce que ces commentaires soient également suivis et maintenus. Par exemple :
# TODO: Optimiser cette fonction pour de meilleures performances
- Exceptions et Cas Particuliers : Si vous gérez des cas particuliers ou des exceptions qui ne sont pas évidents, des commentaires peuvent aider à clarifier pourquoi une solution a été choisie. Cela permet de mieux comprendre les décisions qui ont été prises.
Dans un code propre, les commentaires sont un complément, pas un substitut à la clarté du code. Ils doivent être utilisés pour améliorer la compréhension et fournir des informations essentielles sans surcharger le code de détails inutiles. Un bon équilibre entre un code lisible et des commentaires pertinents est la clé d'un code maintenable et efficace.
Un code propre réussit tous les tests.
Si seulement 95 % de vos tests passent, c’est un signal d’alerte. Pire encore, une couverture de tests à 0 % signifie que vous travaillez sans filet. Un code propre est pleinement testé, assurant ainsi sa robustesse.
Un code propre est économique à long terme.
Un code bien écrit est moins coûteux à maintenir. Il réduit la complexité, les erreurs, et donc le temps passé à corriger ou à faire évoluer le projet. En fin de compte, cela diminue les frais techniques.
Publié le