Tansoftware - Clean Code 
- Introduction
- Nommage des variables
- Gestion des erreurs et des exceptions
- Fonctions courtes et spécifiques
- Respect des conventions de codage
- Documentation de code
- Structure du code claire et organisée
- Utilisation de tests unitaires
- Gestion de dépendances
- Gestion de la complexité du code
- Les fonctions doivent faire une seule chose et la faire bien
Développé et affiné par de nombreux programmeurs et experts en informatique au fil des ans, le clean code a été popularisé par Robert C. Martin.
Le code propre, permet d'améliorer la lisibilité, la maintenabilité et la qualité globale du code. Il facilite la collaboration entre les membres de l'équipe et peut améliorer l'expérience utilisateur finale.
Dans ce dépôt, nous faisons le tour de ces différents grands principes et pratiques via des exemples en PhP.
Donner des noms significatifs et explicites à vos variables facilite la lecture et la compréhension du code par vous-même et par les autres membres de l'équipe. Des noms de variables clairs et compréhensibles peuvent également contribuer à réduire les erreurs et à améliorer la qualité du code.
| Nom de variable | Mauvais exemple | Bon exemple | Explication |
|---|---|---|---|
| Variables simples | a |
age |
Les noms de variables doivent être significatifs et explicites pour faciliter la compréhension du code. |
| Fonctions | foo |
calculateTotal |
Les noms de fonctions doivent refléter leur but et leur utilisation pour faciliter leur compréhension et leur utilisation. |
| Classes | MyClass |
CustomerOrder |
Les noms de classes doivent refléter leur objet et leur responsabilité pour faciliter la compréhension et l'utilisation. |
| Constantes | PI |
MAX_RETRY_ATTEMPTS |
Les noms de constantes doivent être en majuscules et refléter leur utilisation pour faciliter la compréhension du code. |
| Booléens | $bool |
$isLoggedin |
Les noms de variables booléennes doivent refléter leur utilisation pour faciliter la compréhension du code. |
| Tableaux | $arr |
$userList |
Les noms de tableaux doivent refléter leur contenu pour faciliter la compréhension du code. |
| Objets | $obj |
$customerOrderObject |
Les noms d'objets doivent refléter leur objet et leur responsabilité pour faciliter la compréhension et l'utilisation. |
| Arguments de fonctions | $arg1 et $arg2 |
$firstName et $lastName |
Les noms d'arguments de fonctions doivent refléter leur utilisation et leur contenu pour faciliter la compréhension. |
| 🔝 Retour en haut de page |
Il est important de limiter l'utilisation de commentaires à des cas spécifiques pour éviter de surcharger le code avec des explications inutiles ou des commentaires redondants. Les commentaires doivent être utilisés avec parcimonie pour expliquer les parties les plus complexes du code et les décisions de conception clés.
| Commentaires utiles | Exemples de commentaires à éviter | Exemples de commentaires utiles | Explication |
|---|---|---|---|
| Explications de code complexe | // incrémenter x |
// incrémenter x pour parcourir l'ensemble des éléments du tableau |
Les commentaires doivent être utilisés pour expliquer des parties de code complexes ou difficiles à comprendre. |
| Justification de décisions | // Utiliser cette méthode |
// Utiliser cette méthode pour améliorer les performances |
Les commentaires peuvent être utilisés pour justifier les décisions de conception ou les choix de technologie. |
| Erreurs connues | // Erreur ici |
// Corriger l'erreur de débordement en utilisant une boucle pour limiter la valeur de la variable |
Les commentaires peuvent être utilisés pour signaler des erreurs connues ou des bogues à corriger. |
| Documentation d'API | // Renvoie un objet JSON |
// Renvoie un objet JSON contenant les détails du produit |
Les commentaires peuvent être utilisés pour documenter les API et les fonctions, décrivant ce qu'elles font et comment les utiliser. |
| Avertissements sur les effets secondaires | // Modifie l'état global |
// Modifie l'état global, cela peut affecter d'autres parties du code |
Les commentaires peuvent être utilisés pour avertir des effets secondaires ou des impacts potentiels sur le reste du code. |
Il est important de maintenir des fonctions courtes et spécifiques pour faciliter la lecture et la compréhension du code par vous-même et par les autres membres de l'équipe.
| Fonctions courtes et spécifiques | Exemples de fonctions à éviter | Exemples de fonctions utiles | Explication |
|---|---|---|---|
| Longueur des fonctions | function processInput($input) { ...} |
function getInput($input) { ...} |
Les fonctions doivent être courtes et précises pour faciliter la compréhension et la réutilisation du code. |
| Spécificité des fonctions | function process($data) { ...} |
function validateData($data) { ...} |
Les fonctions doivent être spécifiques et ne faire qu'une seule chose pour faciliter la compréhension et la réutilisation du code. |
| 🔝 Retour en haut de page |
Il est important de respecter les conventions de codage pour faciliter la lecture et la compréhension du code par vous-même et par les autres membres de l'équipe. Des conventions de codage cohérentes peuvent contribuer à réduire les malentendus et les conflits de style de codage, ce qui peut améliorer la qualité et l'efficacité du travail en équipe.
| Conventions de codage | Mauvaises conventions à éviter | Bonnes conventions utiles | Explication |
|---|---|---|---|
| Nom de variable | $a |
$age |
Les noms de variables doivent être significatifs et explicites pour faciliter la compréhension du code. |
| Nom de fonction | function doit() |
function calculeTotal() |
Les noms de fonctions doivent refléter leur but et leur utilisation pour faciliter leur compréhension et leur utilisation. |
| Indentation | if($x == 5){ |
if ($x == 5) { |
L'indentation doit être cohérente pour faciliter la compréhension du code. |
| Utilisation des espaces | $a=$b+$c; |
$a = $b + $c; |
Les espaces doivent être utilisés de manière cohérente pour faciliter la compréhension du code. |
| Commentaires | // incrémenter x |
// incrémenter x pour parcourir l'ensemble des éléments du tableau |
Les commentaires doivent être utilisés de manière judicieuse pour faciliter la compréhension du code. |
| 🔝 Retour en haut de page |
Il est important d'éviter la duplication de code pour faciliter la maintenance et la lisibilité du code. Les fonctions réutilisables, les bibliothèques tierces et les frameworks peuvent aider à réduire la duplication de code, tandis que la structuration cohérente du code peut améliorer sa réutilisabilité et sa maintenabilité.
| Mauvaises pratiques à éviter | Bonnes pratiques utiles | Explication | |
|---|---|---|---|
| Réutilisation de code | if (isset($data['name']) && !empty($data['name'])) { ... } |
if (notEmpty($data['name'])) { ... } |
Les fonctions réutilisables peuvent être appelées plusieurs fois dans le code, réduisant la quantité de code nécessaire et facilitant la maintenance du code. |
| Utilisation de bibliothèques | require_once('path/to/validation.php'); validateEmail($email); |
use Illuminate\Validation\Validator; $validator = Validator::make(...) |
Les bibliothèques tierces et les frameworks peuvent fournir des fonctionnalités courantes pour les applications web, telles que l'authentification, la gestion des sessions et la validation des formulaires, permettant de réduire la quantité de code nécessaire et d'améliorer la qualité globale du code. |
| Structuration de code | function addUser() { $user = new User(); ... } function addProduct() { ... } |
class User { function add() { ... } } class Product { function add() { ... } } |
Les fonctions et les classes doivent être nommées de manière significative et être regroupées de manière logique pour faciliter leur utilisation et leur compréhension. Les classes peuvent encapsuler la logique de plusieurs fonctions pour améliorer la réutilisabilité et la maintenabilité du code. |
| 🔝 Retour en haut de page |
L'utilisation de tests unitaires est importante pour améliorer la qualité et la fiabilité du code, réduire les erreurs et les bogues, faciliter la maintenance et améliorer la confiance dans le code. Les pratiques pour utiliser des tests unitaires comprennent l'écriture de tests automatisés pour chaque module de code, l'utilisation de frameworks modernes et fiables, l'exécution régulière des tests unitaires et l'implémentation de tests complets et fiables.
| Utilisation de tests unitaires | Mauvaises pratiques à éviter | Bonnes pratiques utiles | Explication |
|---|---|---|---|
| Écriture de tests automatisés | Aucun test unitaire écrit | Écrire des tests unitaires pour chaque module de code | Les tests unitaires sont utilisés pour vérifier la fonctionnalité d'un module de code spécifique et pour s'assurer que les modifications apportées au code n'ont pas introduit de nouveaux problèmes. Les tests unitaires peuvent également aider à documenter le comportement attendu du code et à faciliter la maintenance en détectant rapidement les erreurs lorsqu'elles se produisent. |
| Utilisation de frameworks | Utiliser des outils de test obsolètes ou peu fiables | Utiliser des frameworks de test modernes et fiables | Les tests unitaires peuvent être écrits à l'aide de différents outils et frameworks, tels que PHPUnit pour PHP, JUnit pour Java et NUnit pour .NET. Les frameworks de test modernes et fiables offrent une meilleure prise en charge des assertions, un reporting amélioré et une intégration avec d'autres outils de développement. |
| Exécution régulière de tests | Exécuter les tests unitaires manuellement de temps en temps | Intégrer les tests unitaires dans le processus de développement et les exécuter régulièrement | Les tests unitaires doivent être exécutés régulièrement pour s'assurer que le code fonctionne correctement et pour détecter les erreurs ou les bogues dès qu'ils se produisent. Les tests unitaires peuvent être intégrés dans des environnements de développement intégrés (IDE) tels que Visual Studio ou Eclipse pour une exécution facile et automatisée. |
| Implémentation de tests complets | Écrire des tests unitaires incomplets ou peu fiables | Écrire des tests unitaires complets et fiables | Les tests unitaires doivent être complets et fiables pour s'assurer que toutes les parties du code fonctionnent correctement. Les tests unitaires doivent également être maintenus et mis à jour en fonction des modifications apportées au code pour s'assurer qu'ils continuent à fournir une couverture adéquate du code. |
| 🔝 Retour en haut de page |
La documentation de code est importante pour aider les développeurs à comprendre le code existant et à ajouter de nouvelles fonctionnalités au logiciel. Les pratiques pour documenter le code comprennent l'écriture de documents de référence externes utiles et à jour, l'utilisation de noms significatifs et bien nommés pour les variables, les fonctions et les classes, et l'utilisation de formats de code cohérents et lisibles pour améliorer la lisibilité et la compréhension du code.
| Documentation de code | Mauvaises pratiques à éviter | Bonnes pratiques utiles | Explication |
|---|---|---|---|
| Documentation externe | Absence de documentation externe ou documentation insuffisante | Écrire des documents de référence externes utiles et à jour | Les documents de référence externes peuvent inclure des guides de style de code, des guides de développement, des manuels d'utilisation, des spécifications de conception et des diagrammes de flux de données. Les documents de référence doivent être utiles et à jour pour aider les développeurs à comprendre le code et à ajouter de nouvelles fonctionnalités au logiciel. |
| Utilisation de noms significatifs | Utilisation de noms de variables, de fonctions et de classes peu significatifs ou mal nommés | Utilisation de noms significatifs et bien nommés pour les variables, les fonctions et les classes | Les noms significatifs et bien nommés peuvent aider à améliorer la compréhension du code et à faciliter la maintenance. Les noms doivent être significatifs et refléter clairement la fonction ou l'objectif de la variable, de la fonction ou de la classe. Les noms doivent également être cohérents et suivre les conventions de nommage du langage de programmation utilisé. |
| Utilisation de formats de code | Absence de formats de code cohérents et lisibles | Utilisation de formats de code cohérents et lisibles pour améliorer la lisibilité et la compréhension du code | Les formats de code cohérents et lisibles peuvent aider à améliorer la lisibilité et la compréhension du code. Les formats doivent être cohérents et suivre les conventions de codage du langage de programmation utilisé. Les formats doivent également être maintenus et mis à jour en fonction des modifications apportées au code pour s'assurer qu'ils restent pertinents. |
| 🔝 Retour en haut de page |
La gestion des erreurs et des exceptions est une pratique importante du Clean Code, car elle permet d'identifier et de résoudre rapidement les problèmes dans le code. Les erreurs et les exceptions sont des éléments inévitables de tout programme, mais leur gestion efficace peut contribuer à éviter les bogues et les erreurs de production. En utilisant les bonnes pratiques pour gérer les erreurs et les exceptions, on peut faciliter le processus de débogage et de résolution des problèmes, tout en améliorant la qualité globale du code.
| Gestion des erreurs et des exceptions | Mauvaises pratiques à éviter | Bonnes pratiques utiles | Explication |
|---|---|---|---|
| Utilisation de die() et exit() | if (!$result) { die('Error: Could not connect to database'); } |
if (!$result) { throw new Exception('Could not connect to database'); } |
Les fonctions die() et exit() arrêtent immédiatement l'exécution du code et empêchent toute gestion ultérieure des erreurs ou des exceptions. Il est préférable d'utiliser des exceptions pour gérer les erreurs, car elles permettent une gestion plus fine et une gestion centralisée des erreurs dans le code. |
| Absence de gestion des erreurs | if (!$result) { echo 'Error: Could not connect to database'; } |
try { ... } catch (Exception $e) { ... } |
L'absence de gestion des erreurs peut entraîner des erreurs fatales et des bogues difficiles à identifier et à corriger. Il est important d'ajouter une gestion des erreurs pour identifier et résoudre rapidement les problèmes. Les exceptions peuvent être utilisées pour capturer les erreurs et les exceptions et les traiter de manière centralisée. Les blocs try/catch peuvent être utilisés pour gérer les exceptions et fournir des messages d'erreur et des informations de débogage appropriés. |
| Utilisation de messages d'erreur | echo 'Error: Could not connect to database'; |
throw new Exception('Could not connect to database'); |
Les messages d'erreur peuvent fournir des informations utiles pour résoudre les problèmes, mais il est préférable d'utiliser des exceptions pour capturer et gérer les erreurs. Les exceptions fournissent une gestion plus fine et une gestion centralisée des erreurs dans le code. Les exceptions peuvent également fournir des informations de débogage supplémentaires pour aider à résoudre rapidement les problèmes. |
| Utilisation de logs | Absence de logs ou logs insuffisants | Utilisation de logs pour enregistrer les erreurs et les exceptions et faciliter la résolution des problèmes de production | Les logs peuvent être utilisés pour enregistrer les erreurs et les exceptions et faciliter la résolution des problèmes de production. Les logs peuvent également fournir des informations supplémentaires pour aider à comprendre les erreurs et les exceptions et à les résoudre plus rapidement. Les logs doivent être pertinents et utiles pour aider à identifier les problèmes. Les outils de surveillance des logs peuvent également être utilisés pour détecter les erreurs et les exceptions et envoyer des alertes pour résoudre rapidement les problèmes. |
| 🔝 Retour en haut de page |
La structure du code claire et organisée est également une pratique importante du Clean Code, car elle contribue à améliorer la lisibilité et la compréhension du code. Le code bien structuré peut être facilement compris et modifié par les développeurs, et peut faciliter le processus de maintenance et d'évolution du code. En utilisant les bonnes pratiques pour structurer le code de manière claire et organisée, on peut améliorer la qualité du code et faciliter son évolutivité.
| Structure du code claire et organisée | Mauvaises pratiques à éviter | Bonnes pratiques utiles | Explication |
|---|---|---|---|
| Code désorganisé | Absence de structure claire et de hiérarchie dans le code | Utilisation de la hiérarchie et de la structure du code pour une meilleure lisibilité | Un code désorganisé et sans hiérarchie peut être difficile à lire et à comprendre pour les développeurs. Il est important de structurer le code de manière claire et organisée pour faciliter la lisibilité et la compréhension. Les fonctions et les classes doivent être regroupées de manière logique pour faciliter l'utilisation et la maintenance du code. Les fichiers doivent également être organisés en fonction de leur fonction et de leur objectif. |
| Complexité de la logique | Code complexe avec des boucles imbriquées et une logique difficile à suivre | Simplification de la logique et utilisation de fonctions courtes et spécifiques | La complexité de la logique peut rendre le code difficile à comprendre et à maintenir. Il est important de simplifier la logique et de réduire la complexité autant que possible. Les fonctions courtes et spécifiques peuvent être utilisées pour encapsuler la logique et améliorer la réutilisabilité et la maintenabilité du code. Les boucles imbriquées doivent être évitées autant que possible, car elles peuvent rendre le code difficile à suivre et à comprendre. |
| Commentaires utiles | Absence de commentaires utiles dans le code | Utilisation de commentaires utiles et significatifs pour faciliter la compréhension du code | Les commentaires utiles peuvent aider à expliquer la logique du code et à faciliter la compréhension pour les développeurs. Les commentaires doivent être significatifs et utiles et doivent être utilisés avec parcimonie pour éviter la surcharge de commentaires. Il est important de maintenir les commentaires à jour et de les supprimer s'ils ne sont plus pertinents ou utiles pour le code. |
| Utilisation de standards de codage | Absence de standards de codage clairs et suivis | Utilisation de standards de codage clairs et suivis pour faciliter la maintenance | Les standards de codage clairs et suivis peuvent aider à améliorer la qualité globale du code et à faciliter la maintenance. Les standards de codage doivent être cohérents et suivis par tous les développeurs travaillant sur le code. Les standards de codage peuvent inclure des conventions de nommage, des formats de code et des pratiques de gestion des erreurs et des exceptions. Les outils d'analyse de code peuvent également être utilisés pour détecter les violations des standards de codage et les signaler aux développeurs pour une correction rapide. |
Les dépendances sont des bibliothèques tierces ou des modules externes utilisés par votre application pour ajouter des fonctionnalités ou des fonctionnalités existantes. Bien que l'utilisation de dépendances puisse simplifier la création de logiciels, elle peut également rendre votre code plus complexe et difficile à maintenir.
| Gestion des dépendances | Mauvaises pratiques à éviter | Bonnes pratiques utiles | Explication |
|---|---|---|---|
| Utilisation de dépendances inutiles | require('vendor/autoload.php'); use Vendor\Package\Class; $class = new Class(); |
require('vendor/autoload.php'); use Package\Class; $class = new Class(); |
L'utilisation de dépendances inutiles peut alourdir le code et le rendre plus difficile à maintenir. Il est préférable de limiter l'utilisation des dépendances à celles qui sont nécessaires et de les importer de manière sélective pour éviter les conflits de noms d'espace. |
| Absence de gestion des versions | require('vendor/autoload.php'); use Vendor\Package\Class; $class = new Class(); |
require('vendor/autoload.php'); use Vendor\Package\Class; $class = new Class('1.0.0'); |
L'absence de gestion des versions peut entraîner des problèmes de compatibilité lors de la mise à jour des dépendances. Il est important de spécifier les versions des dépendances pour éviter les conflits de version et faciliter la maintenance du code. |
| Utilisation de dépendances obsolètes | require('vendor/autoload.php'); use Vendor\Package\Class; $class = new Class(); // Version 1.0 |
require('vendor/autoload.php'); use Vendor\Package\Class; $class = new Class('2.0.0'); // Version la plus récente |
L'utilisation de dépendances obsolètes peut entraîner des problèmes de sécurité et de compatibilité. Il est important de mettre à jour régulièrement les dépendances pour bénéficier des nouvelles fonctionnalités et des corrections de bogues, et de retirer les dépendances qui ne sont plus nécessaires. |
| Utilisation de dépendances personnalisées | require('vendor/autoload.php'); use My\Custom\Class; $class = new Class(); |
require('vendor/autoload.php'); use Vendor\Package\Class; use My\Custom\Class; $class = new Class(); |
L'utilisation de dépendances personnalisées peut entraîner des conflits de noms d'espace et des problèmes de compatibilité. Il est préférable d'utiliser des dépendances tierces bien établies plutôt que de créer des dépendances personnalisées, sauf si cela est absolument nécessaire. Si des dépendances personnalisées sont utilisées, il est important de les importer de manière sélective pour éviter les conflits de noms d'espace. |
| 🔝 Retour en haut de page |
La gestion de la complexité est importante pour faciliter la compréhension et la maintenance du code. Les pratiques comprennent la division des fonctions en fonctions plus courtes et plus spécifiques, l'utilisation d'expressions logiques simples plutôt que de logique imbriquée, la réduction des niveaux d'indentation et des branches conditionnelles excessives.
| Gestion de la complexité du code | Mauvaises pratiques à éviter | Bonnes pratiques utiles | Explication |
|---|---|---|---|
| Fonctions trop longues | function processOrders($orders) { foreach ($orders as $order) { ... } } |
function processOrders($orders) { validateOrders($orders); processValidOrders($orders); } |
Les fonctions trop longues sont difficiles à comprendre et à maintenir. Il est préférable de diviser les fonctions en fonctions plus courtes et plus spécifiques pour faciliter la compréhension et la maintenance du code. |
| Trop de logique imbriquée | if ($a == $b) { if ($b == $c) { if ($c == $d) { ... } } } |
if ($a == $b && $b == $c && $c == $d) { ... } |
La logique imbriquée est difficile à lire et à comprendre. Il est préférable d'utiliser des expressions logiques simples plutôt que de recourir à des structures de contrôle complexes pour améliorer la lisibilité et la compréhension du code. |
| Trop de niveaux d'indentation | if ($a) { if ($b) { if ($c) { if ($d) { ... } } } } |
if (!$a) { return; } if (!$b) { return; } if (!$c) { return; } if (!$d) { return; } ... |
Les niveaux d'indentation excessifs sont difficiles à lire et à comprendre. Il est préférable d'utiliser des structures de contrôle simples et des fonctions claires pour réduire les niveaux d'indentation. |
| Trop de branches conditionnelles | if ($a == $b) { ... } else if ($a == $c) { ... } else if ($a == $d) { ... } else { ... } |
switch ($a) { case $b: ...; break; case $c: ...; break; case $d: ...; break; default: ...; } |
Les branches conditionnelles excessives sont difficiles à lire et à comprendre. Il est préférable d'utiliser des structures de contrôle simples pour réduire les branches conditionnelles. Si les branches conditionnelles sont nécessaires, il est préférable d'utiliser une instruction switch plutôt que des instructions if/else imbriquées. |
| 🔝 Retour en haut de page |
Les fonctions doivent avoir une seule responsabilité et être spécialisées dans cette tâche.
| Fonctions courtes et spécifiques | Mauvaises pratiques à éviter | Bonnes pratiques utiles | Explication |
|---|---|---|---|
| Fonctions trop longues | function processFormData($data) { if (isset($data['name']) && !empty($data['name'])) { $name = sanitizeString($data['name']); if (isset($data['email']) && !empty($data['email'])) { $email = sanitizeEmail($data['email']); if (isset($data['message']) && !empty($data['message'])) { $message = sanitizeString($data['message']); sendEmail($name, $email, $message); return true; } } } return false; } |
function processFormData($data) { $name = getName($data); $email = getEmail($data); $message = getMessage($data); sendEmail($name, $email, $message); return true; } function getName($data) { return sanitizeString($data['name']); } function getEmail($data) { return sanitizeEmail($data['email']); } function getMessage($data) { return sanitizeString($data['message']); } |
Les fonctions trop longues peuvent être difficiles à comprendre et à maintenir. Il est préférable de décomposer la logique en fonctions plus petites et spécialisées pour faciliter leur réutilisation et leur maintenabilité. Les fonctions courtes et spécifiques permettent également de faciliter la lecture et la compréhension du code en isolant les différentes tâches à accomplir. |
| Trop de tâches dans une fonction | function sendEmail($data) { $to = $data['to']; $subject = $data['subject']; $message = $data['message']; $headers = "From: ".$data['from']; mail($to, $subject, $message, $headers); } |
function sendEmail($to, $subject, $message, $from) { $headers = "From: ".$from; mail($to, $subject, $message, $headers); } |
Les fonctions ne doivent avoir qu'une seule responsabilité. Les fonctions qui effectuent plusieurs tâches peuvent être difficiles à comprendre et à maintenir. Il est préférable de décomposer les tâches en fonctions plus petites et spécialisées pour faciliter leur réutilisation et leur maintenabilité. Les fonctions courtes et spécifiques permettent également de faciliter la lecture et la compréhension du code en isolant les différentes tâches à accomplir. |
| Répétition de code dans les fonctions | `function getUser($id) { $conn = mysqli_connect('localhost', 'username', 'password', 'database'); $sql = "SELECT * FROM users WHERE id = $id"; $result = mysqli_query($conn, $sql); $user = mysqli_fetch_assoc($result); mysqli_close($conn); return $user; } function getProduct($id) { $conn = mysqli_connect('localhost', 'username', 'password', 'database'); $sql = "SELECT * FROM products WHERE id = $id"; $result = mysqli_query($conn, $sql); $product = mysqli_fetch |
React
Typescript
Django
Laravel
Facebook
Microsoft
Google
Alibaba
D3
Tencent