Les bonnes pratiques

 

 

https://github.com/chrislgarry/Apollo-11

Bonnes pratiques en programmation

1. Lisibilité du code

• Commentaires appropriés : Expliquez le pourquoi du code (pas seulement le comment). Les commentaires doivent être concis et aider à comprendre la logique ou les choix de conception, mais sans en abuser.
• Noms significatifs : Utilisez des noms de variables, fonctions et classes qui sont clairs et décrivent précisément leur rôle (par exemple, getUserName() au lieu de funct1()).
• Indentation et formatage : Utilisez une indentation cohérente (généralement 2 ou 4 espaces) pour structurer le code.
• Lignes de code courtes : Limitez la longueur des lignes de code à environ 80-120 caractères pour améliorer la lisibilité.On retrouvera tout cela plus loin dans la partie norme !

2. Modularité et réutilisabilité

• Fonctions courtes et spécifiques : Chaque fonction doit effectuer une tâche spécifique. Si une fonction fait trop de choses, décomposez-la en fonctions plus petites.
• Réutilisation du code : Ne dupliquez pas le code. Si un bloc de code est utilisé plusieurs fois, placez-le dans une fonction réutilisable.
• Encapsulation : Cachez les détails internes d’une classe ou d’un module et exposez uniquement les méthodes ou propriétés nécessaires.

3. Principes de conception solides

• DRY (Don’t Repeat Yourself) : Évitez la duplication de code. Si une logique est répétée, mettez-la dans une fonction ou une méthode réutilisable.
• KISS (Keep It Simple, Stupid) : Gardez le code aussi simple que possible. Un code complexe est plus difficile à maintenir et à déboguer.
• YAGNI (You Aren’t Gonna Need It) : N’implémentez pas de fonctionnalités avant qu’elles ne soient réellement nécessaires.
• SOLID : Principes de conception orientée objet :
  • S : Single Responsibility Principle – Une classe doit avoir une seule responsabilité.
  • O : Open/Closed Principle – Une classe doit être ouverte à l’extension, mais fermée à la modification.
  • L : Liskov Substitution Principle – Les objets d’une classe dérivée doivent pouvoir être substitués à ceux de la classe de base.
  • I : Interface Segregation Principle – Les interfaces doivent être spécifiques aux besoins des clients.
  • D : Dependency Inversion Principle – Les classes doivent dépendre des abstractions plutôt que des implémentations concrètes.

4. Gestion des erreurs et des exceptions

• Gérer les erreurs proprement : Utilisez des exceptions pour gérer les erreurs au lieu d’utiliser des codes de retour.
• Validation des entrées : Validez toujours les entrées utilisateur et les données externes pour prévenir les erreurs et les failles de sécurité.
• Journalisation : Loggez les erreurs et les événements importants pour faciliter le débogage et le suivi du comportement de l’application.

5. Tests

• Tests unitaires : Écrivez des tests unitaires pour vérifier que chaque composant de votre code fonctionne correctement.
• Tests automatisés : Utilisez des frameworks de tests comme PHPUnit, Jest, ou PyTest pour automatiser les tests.
• Testez les cas d’erreurs : Ne testez pas seulement les scénarios réussis. Testez aussi les cas où le code doit échouer.

6.Contrôle de version

• Utilisez un système de contrôle de version (VCS) : Utilisez un système comme Git pour gérer l’historique des modifications et collaborer.
• Commits fréquents et descriptifs : Faites des commits régulièrement avec des messages descriptifs. Un commit n’est pas une sauvegarde mais un ajout de fonctionnalité ou un déboggage !

7. Documentation

• Documentez votre code : Utilisez des commentaires PHPDoc, JSDoc ou d’autres normes de documentation pour décrire vos fonctions, classes, et modules.
• Documentation externe : Rédigez une documentation externe (par exemple, un fichier README.md) pour expliquer le projet, ses dépendances, et son utilisation. Les fichiers README.md sont des fichiers écrit en Markdown.

8. Optimisation

• Évitez l’optimisation prématurée : Optimisez seulement lorsque cela est nécessaire, après avoir identifié des points faibles de performance.
• Utilisez les bonnes structures de données : Assurez-vous que les structures de données utilisées sont adaptées à vos besoins. Exemple de structures : objets, tableaux, listes, piles, files, graphes, arbres, etc.
  

  Bill Gates

9. Sécurité

• Protégez les entrées et les sorties : Utilisez des méthodes comme l’échappement de contenu pour éviter les attaques XSS et des requêtes préparées pour prévenir les injections SQL.
• Chiffrement des données sensibles : Chiffrez les informations sensibles comme les mots de passe ou les numéros de carte de crédit.
• Authentification et autorisation : Utilisez des systèmes d’authentification robustes et vérifiez les permissions des utilisateurs.

10. Performances

• Minimisez les requêtes coûteuses : Évitez de faire des appels coûteux en boucle, comme les requêtes SQL répétitives ou les appels API.
• Mise en cache : Utilisez la mise en cache lorsque c’est possible pour éviter les recalculs inutiles ou les appels redondants à des ressources externes.
  

  Guido van Rossum

11. Les normes

• Indentation : elle permet d’un seul coup d’oeil d’identifier un groupe d’instruction ou la profondeur des tests ou boucles. Elle s’applique au HTML, CSS, JS, PHP, etc.
  Cette indentation d’après la norme PSR-12 : Extended Coding Guide (norme pour le PHP mais chaque langage à ses normes qui partagent 80% des concepts) est de 4 espaces et pas de tabulations !
• Longueur des lignes : max 80 caractères (exception 120 dans des cas spécifiques)
• Programmation
  Essayer de mettre une instruction par ligne (une action)
  N’essayez pas de faire trop compacte ni trop aérée. Un juste milieu est souhaitable.
  Pour le bon niveau il manque la bonne disposition des accolades (voir plus loin) :
• Espaces autour des opérateurs : mettre un espace avant et après les opérateurs ( =, +,-, etc )
• Règles de nommage
  • Eviter les nom de variables de type i, j, n, truc mais prenez des noms de variables porteur de sens comme nbClient, surfaceCercle, noCommande.
  • On peut utiliser les accents dans les variables même si les anciens développeurs s’en méfie toujours 😉
  • Après avoir choisi vos noms de variables soyez cohérent si vous commencer avec _ exemple : nombre_de_client continuer avec l’_ sinon prenez la notation low Camel (camelCase) nombreDeClient mais restez avec ce type de notation.
  • Normalement camelCase pour les fonctions et variables et PascalCase pour les classes.
  • Idem soit vous prenez des variables avec des noms anglais car votre application est communautaire et à vocation internationale et dans ce cas restez dans l’anglais soit prenez des noms français mais ne faites pas de mélange. Utiliser toujours les mêmes préfixes permis une liste de type : nb, is, get, calc, send, save, format…

• Les noms des variables, des fonctions, des méthodes et des attributs sont écrits en camelCase.

$myVar = 3;
function sumAllNumbers($max) {...}

Les noms des clés dans un tableau sont écrits en snake_case. Le mot clé array n’est plus utilisé pour les tableaux.

$user = [
   'username' => 'monadresse@mail.com',
   'first_name' => 'John',
   'last_name' => 'Doe',
   'active' => 1
];

• Les noms des constantes sont écrits en MAJUSCULE

define('LUCKY_NUMBER', 13);

Les noms des objets sont écrits en PascalCase et avec des soulignements pour séparer les mots. Chaque objet est stocké dans un fichier qui porte le même nom que l’objet et ne contient que cet objet.

class Hero
{
...
}

Mots-clés

En programmation orientée objet, la visibilité des propriétés et méthodes doit toujours être déclarée. Les mots-clés abstract et final doivent être déclarés avant la visibilité. Le mot-clé static lui doit être déclaré après la visibilité.

Les mots-clés true, false et null doivent toujours êtres écrits en minuscule.

Accolades et espaces

• Les accolades en PHP sont à la ligne suivant la déclaration d’une classe, d’une fonction ou d’une méthode.

class Hero
{
    // Nom de mon Héros
    public string $name = '';
    
    // Constructeur
    public function __construct(string $name)
    {
        $this->name = $name;
    }
}

Les accolades en PHP sont à la suite, précédée d’un espace, pour un if, switch, while, foreach, match, etc. et sont obligatoires.

function calculSommeNombresPairs($maximum)
{
    $somme = 0;
    for ($i = 1; $i <= $maximum; $i++) {
        if ($i % 2 == 0) {
            $somme += $i;   
        }
    }

    return $somme;
}

On ne met pas d’espace entre le nom d’une fonction et l’appel de ses paramètres. Même chose à la création d’un objet. Seul echo fait exception.

$sum = calculSumPairNumbers(200);
echo $sum;

$hero = new Hero('Actarus');
echo $hero->getName();

• Nommage explicite et utilisation de constantes

Les noms des variables, des fonctions, méthodes et classes doivent être le plus explicites possibles.

// Evitez absolument les abbréviations, qui laissent place à l'interprétation
// Pas bon :
$numUser;
// Bon :
$mobilePhoneNumberUser;

Utilisez des constantes pour réaliser des comparaisons de nombre ou de chaînes de caractères. Ce principe est très intéressant pour avoir un code beaucoup plus lisible. De plus, si vous faites une faute de frappe sur une constante, PHP déclenchera une erreur, alors que si vous faites une faute de frappe dans une chaîne de caractères, PHP ne déclenchera pas d’erreur :

// Je teste le statut d'une commande
if ($order['status'] == 1) {
    // Certaines instructions
}

if ($order['status'] == 2) {
    // D'autres instructions
}

// Préférez : (en ayant défini les constantes préalablement bien sûr)
if ($order['status'] == ORDER_STATE_OPEN) {
    // Certaines instructions pour une commande ouverte
}

if ($order['status'] == ORDER_STATE_PAYED) {
    // D'autres instructions pour une commande payée
}

// Cette fois-ci je teste la présence d'un langage dans un tableau de compétences.
if (in_array('html', $skills)) {
    // Certaines instructions
}

// Le code ci-dessous n'est pas bon mais ne génère pas d'erreur :
if (in_array('hmtl', $skills)) {
    // Certaines instructions
}

// Alors qu'avec une constante, disons LANGAGE_HTML, ce code génère une erreur :
if (in_array(LANGAGE_HMTL, $skills)) {
    // Certaines instructions
}

Organisation des fichiers :

• Chaque fichier doit commencer par la balise <?php sans espace ou caractère avant.
• Il ne doit pas y avoir de fermeture PHP (?>) à la fin d’un fichier contenant que du code PHP.
• Espace après les parenthèses et avant les accolades. : if ($conditions) {
  Par contre les parenthèses doivent être collées au nom de la fonction ou méthode sans espace :  addition(int $a,int $b): int
• Commentaires
  Les commentaires sont aussi indispensables que l’indentation pour assurer une lisibilité et une durabilité maximales du code. N’oubliez pas que vous devrez probablement revoir vos scripts quelques mois ou quelques années plus tard. Et que même si vous n’êtes plus là, un collègue devra se charger de revenir sur vos travaux pour des maintenances correctives (correction de bogue) ou évolutives (ajout de fonctionnalités).
  Un commentaire pertinent ne dois pas répéter le code mais expliquer par exemple l’objet d’une boucle ou ce qu’elle permet.
• Documentation
  L’habitude veut que chaque fichier d’un projet débute par une courte introduction sous forme de commentaires indiquant le but du fichier, sa version, l’auteur, les travaux en cours.
  Idem chaque fonction commence par une documentation de cette fonction.
  Voici un exemple en PHPDoc

Pourquoi faut-il des normes en programmation ?

Les normes en programmation sont des conventions, des règles et des guidelines que les développeurs suivent pour écrire du code de manière cohérente, efficace, et maintenable. Il existe plusieurs raisons pour lesquelles ces normes sont essentielles, que ce soit pour des projets individuels ou pour des projets en équipe.

1. Lisibilité et compréhension du code

Les normes garantissent que le code est facile à lire et à comprendre, non seulement pour son auteur, mais aussi pour d’autres développeurs.

2. Maintenance et évolutivité

Le code évolue souvent avec le temps. Les normes facilitent la maintenance du code en rendant les modifications moins risquées et plus faciles à effectuer. En suivant des conventions claires, les développeurs peuvent anticiper la structure et l’organisation du code, ce qui simplifie les mises à jour et les corrections de bugs.

 

3. Travail en équipe et collaboration

Dans les projets d’équipe, chaque développeur a son propre style de codage. Sans normes, cela peut mener à un code incohérent et difficile à gérer. Les normes assurent que chaque membre de l’équipe écrit du code d’une manière compatible avec celle des autres.

4. Détection et prévention des erreurs

Les normes encouragent des pratiques qui minimisent les erreurs et les bugs potentiels. Des règles comme ne pas dupliquer le code, bien gérer les erreurs et valider les entrées peuvent réduire le risque d’introduire des failles dans le code.

5. Sécurité

Les normes en matière de sécurité aident à prévenir les failles courantes dans le code, comme les injections SQL, les failles XSS, ou la gestion incorrecte des mots de passe.

6. Performance

Les normes aident à écrire un code plus performant en suivant des pratiques qui optimisent l’utilisation des ressources. Elles encouragent l’utilisation des bonnes structures de données et des algorithmes efficaces.

7. Réutilisabilité

Les normes favorisent l’écriture de code réutilisable. Des fonctions ou des classes bien définies peuvent être facilement réutilisées dans d’autres parties du projet ou même dans d’autres projets.

8. Conformité aux standards de l’industrie

Les normes de codage comme PSR-12 en PHP ou PEP-8 en Python ne sont pas seulement des bonnes pratiques internes, mais aussi des standards de l’industrie. En les suivant, vous facilitez l’intégration avec des outils, des frameworks, et des bibliothèques tierces.

• Interopérabilité : En respectant les standards de l’industrie, votre code sera plus compatible avec des projets open-source, des frameworks, ou des outils d’analyse statique.

9. Automatisation et outils de contrôle de qualité

Lorsque des normes sont définies, il est possible d’automatiser leur vérification via des outils comme PHP_CodeSniffer, ESLint (pour JavaScript), ou Flake8 (pour Python). Ces outils détectent automatiquement les violations des normes et aident à corriger les erreurs avant même que le code ne soit fusionné dans le projet principal.

• Analyse statique : Les outils d’analyse statique permettent de détecter les erreurs potentielles, les mauvaises pratiques et les écarts par rapport aux normes.

Conclusion

Les normes en programmation ne sont pas seulement des règles arbitraires ; elles sont mises en place pour garantir que le code soit lisible, maintenable, sécurisé, et performant. En suivant ces normes, les développeurs s’assurent que leur code est facile à comprendre, à améliorer, et à corriger, tout en réduisant les risques d’erreurs et de failles de sécurité. Elles sont particulièrement cruciales dans les projets collaboratifs où plusieurs développeurs doivent travailler ensemble efficacement.