Add software engineering principles and enhance Java documentation

Author: fpluquet

docs/.vitepress/config.ts

@@ -73,6 +73,16 @@ export default withMermaid({
               { text: 'Structural', link: '/cours/design-patterns/4-structural' },
               { text: 'Behavioral', link: '/cours/design-patterns/5-behavioral' },
             ]
+          },
+          {
+            text: 'Génie logiciel',
+            items: [
+              { text: 'Introduction', link: '/cours/genie-logiciel/introduction' },
+              { text: 'Simplicité et clarté', link: '/cours/genie-logiciel/simplicite-et-clarte' },
+              { text: 'Réutilisabilité et maintenabilité', link: '/cours/genie-logiciel/reutilisabilite-et-maintenabilite' },
+              { text: 'Conception orientée objet', link: '/cours/genie-logiciel/conception-orientee-objet' },
+              { text: 'Robustesse et gestion des erreurs', link: '/cours/genie-logiciel/robustesse-et-erreurs' },
+            ]
           }
         ]
       }

docs/cours/genie-logiciel/conception-orientee-objet.md

@@ -0,0 +1,139 @@
+# Conception orientée objet
+
+La programmation orientée objet, telle une architecture savante, repose sur des principes qui en garantissent la solidité, la souplesse et la beauté. Ces principes, forgés par l’expérience et la réflexion, sont les fondations sur lesquelles s’élèvent les logiciels robustes et évolutifs. Parmi eux, les fameux SOLID, mais aussi la Loi de Demeter, tracent la voie d’un code élégant et pérenne. Plongeons dans ces piliers, en les éclairant d’exemples concrets et de réflexions issues du terrain.
+
+## SOLID
+Les cinq principes SOLID sont des boussoles pour l’ingénieur logiciel. Ils guident la conception vers la clarté, la modularité et la facilité d’évolution.
+
+### S — Single Responsibility Principle (Responsabilité unique)
+
+Imaginez une classe comme un artisan spécialisé : elle doit n’avoir qu’une seule mission, une seule raison de changer. Plus une classe s’éparpille, plus elle devient fragile et difficile à maintenir.
+
+**Exemple :**
+
+```java
+// Mauvais exemple : une classe gère trop de choses
+class Rapport {
+    void generer() {}
+    void sauvegarder() {}
+}
+
+// Bon exemple : séparation des responsabilités
+class Rapport {
+    void generer() {}
+}
+class RapportSauvegarde {
+    void sauvegarder(Rapport r) {}
+}
+```
+
+---
+
+### O — Open/Closed Principle (Ouvert/Fermé)
+
+Un bon logiciel doit pouvoir évoluer sans être sans cesse remanié. Les entités doivent être ouvertes à l’extension, mais fermées à la modification. On ajoute, on enrichit, sans tout casser.
+
+**Exemple :**
+
+```java
+// Mauvais exemple : modification de la classe pour chaque nouveau type
+class Facture {
+    double calculerRemise(String type) {
+        if (type.equals("VIP")) return 0.2;
+        else return 0.0;
+    }
+}
+
+// Bon exemple : extension par héritage
+interface Remise {
+    double calculer();
+}
+class RemiseVIP implements Remise {
+    public double calculer() { return 0.2; }
+}
+```
+
+---
+
+### L — Liskov Substitution Principle
+
+L’héritage doit respecter le contrat de la classe mère. Une sous-classe doit pouvoir se substituer à sa classe parente sans altérer le comportement attendu. Sinon, gare aux bugs subtils !
+
+**Exemple :**
+
+```java
+// Mauvais exemple : une sous-classe casse le contrat
+class Rectangle {
+    int largeur, hauteur;
+    void setLargeur(int l) { largeur = l; }
+    void setHauteur(int h) { hauteur = h; }
+}
+class Carre extends Rectangle {
+    void setLargeur(int l) { largeur = hauteur = l; }
+    void setHauteur(int h) { largeur = hauteur = h; }
+}
+
+// Bon exemple : ne pas forcer l’héritage
+class Rectangle { /* ... */ }
+class Carre { /* ... */ }
+```
+
+---
+
+### I — Interface Segregation Principle
+
+Il vaut mieux plusieurs interfaces précises qu’une seule interface fourre-tout. Ainsi, chaque classe n’implémente que ce dont elle a réellement besoin, et le code reste clair et flexible.
+
+**Exemple :**
+
+```java
+// Mauvais exemple : interface trop large
+interface Machine {
+    void imprimer();
+    void scanner();
+    void faxer();
+}
+
+// Bon exemple : interfaces spécifiques
+interface Imprimante { void imprimer(); }
+interface Scanner { void scanner(); }
+```
+
+---
+
+### D — Dependency Inversion Principle
+
+Pour un code souple et testable, il faut dépendre d’abstractions plutôt que de classes concrètes. On injecte les dépendances, on ne les crée pas en dur.
+
+**Exemple :**
+
+```java
+// Mauvais exemple : dépendance directe
+class Service {
+    private Database db = new Database();
+}
+
+// Bon exemple : injection de dépendance
+class Service {
+    private IDatabase db;
+    public Service(IDatabase db) { this.db = db; }
+}
+```
+
+---
+
+## Law of Demeter (LoD)
+
+La Loi de Demeter, ou « principe du moindre couplage », recommande de ne parler qu’à ses proches collaborateurs. Plus on limite les chaînes d’appels, plus le code est robuste et facile à faire évoluer.
+
+**Exemple :**
+
+```java
+// Mauvais exemple : chaîne d’appels
+client.getCommande().getFacture().payer();
+
+// Bon exemple : délégation
+client.payerFacture();
+```
+
+En respectant ces principes, on bâtit des architectures solides, prêtes à affronter les évolutions et les défis du temps.

docs/cours/genie-logiciel/introduction.md

@@ -0,0 +1,24 @@
+# Introduction au génie logiciel
+
+Le génie logiciel est l’art et la science de concevoir, développer, tester et maintenir des logiciels de qualité. Bien plus qu’une simple activité de programmation, il s’agit d’une discipline structurée, qui s’appuie sur des principes, des méthodes et des outils pour répondre aux besoins des utilisateurs tout en maîtrisant la complexité croissante des systèmes informatiques.
+
+## Pourquoi le génie logiciel ?
+
+À mesure que les logiciels prennent une place centrale dans notre société, les enjeux de fiabilité, de maintenabilité, de performance et d’évolutivité deviennent cruciaux. Le génie logiciel vise à garantir que les applications développées soient robustes, évolutives et compréhensibles, même des années après leur création.
+
+## Les grands principes
+
+Le génie logiciel s’appuie sur des principes fondateurs, tels que la simplicité, la réutilisabilité, la robustesse, la modularité ou encore la séparation des responsabilités. Ces principes, détaillés dans les chapitres suivants, sont illustrés par des exemples concrets et des retours d’expérience issus du monde professionnel.
+
+- [Simplicité et clarté](./simplicite-et-clarte.md)
+- [Réutilisabilité et maintenabilité](./reutilisabilite-et-maintenabilite.md)
+- [Conception orientée objet](./conception-orientee-objet.md)
+- [Robustesse et gestion des erreurs](./robustesse-et-erreurs.md)
+
+## Un métier d’équipe
+
+Développer un logiciel, c’est aussi collaborer : la communication, la documentation, la gestion de projet et le travail en équipe sont au cœur de la réussite. Le génie logiciel propose des méthodes (agiles, cycle en V, etc.) pour organiser efficacement le travail collectif.
+
+## Pour aller plus loin
+
+Ce module vous invite à explorer les fondements du génie logiciel, à travers des concepts théoriques, des bonnes pratiques et des exemples issus de la réalité du terrain. Bonne lecture et bonne exploration !

docs/cours/genie-logiciel/reutilisabilite-et-maintenabilite.md

@@ -0,0 +1,177 @@
+# Réutilisabilité et maintenabilité
+
+Dans l’odyssée du développement logiciel, deux qualités font la différence entre un projet éphémère et une œuvre qui traverse le temps : la réutilisabilité et la maintenabilité. Un code réutilisable est un trésor, car il évite de réinventer la roue. Un code maintenable, lui, est une promesse de sérénité pour l’équipe qui devra le faire évoluer, corriger ou adapter. Ces principes, souvent cités, prennent tout leur sens à travers des pratiques concrètes et des exemples vécus.
+
+## DRY (Don’t Repeat Yourself)
+
+La duplication est l’ennemie du progrès. Chaque répétition de code est une source potentielle d’erreur, un piège pour celui qui devra un jour tout modifier. Le principe DRY nous invite à centraliser la logique, à n’avoir qu’une seule source de vérité pour chaque information ou comportement.
+
+**Exemple :**
+
+```java
+// Mauvais exemple : duplication
+public double surfaceCercle(double rayon) {
+    return 3.14159 * rayon * rayon;
+}
+public double perimetreCercle(double rayon) {
+    return 2 * 3.14159 * rayon;
+}
+
+// Bon exemple : extraire la constante
+public static final double PI = 3.14159;
+public double surfaceCercle(double rayon) {
+    return PI * rayon * rayon;
+}
+public double perimetreCercle(double rayon) {
+    return 2 * PI * rayon;
+}
+```
+
+Un changement de formule ou de constante ne doit se faire qu’à un seul endroit, sous peine de voir le code diverger et les bugs proliférer.
+
+
+## Single Source of Truth (SSOT)
+
+Dans un système bien conçu, chaque information n’existe qu’à un seul endroit. Multiplier les copies, c’est s’exposer à l’incohérence et à la confusion. Le principe SSOT est le garant de la cohérence des données.
+
+**Exemple :**
+
+Imaginons une application qui communique avec une API distante. Si l’URL de cette API est dupliquée dans plusieurs classes, une modification future (changement de domaine, de version, etc.) risque d’être oubliée à un endroit, provoquant des bugs difficiles à diagnostiquer.
+
+```java
+// Mauvais exemple : l’URL de l’API est dupliquée
+class UserService {
+    private static final String API_URL = "https://api.exemple.com/v1/";
+    // ...
+}
+class ProductService {
+    private static final String API_URL = "https://api.exemple.com/v1/";
+    // ...
+}
+
+// Bon exemple : une seule source de vérité
+class Config {
+    public static final String API_URL = "https://api.exemple.com/v1/";
+}
+class UserService {
+    // Utilise Config.API_URL
+}
+class ProductService {
+    // Utilise Config.API_URL
+}
+```
+
+En centralisant l’information, on garantit la cohérence et on simplifie la maintenance.
+
+
+## Separation of Concerns (Séparation des préoccupations)
+
+Un bon logiciel est comme un orchestre : chaque instrument a son rôle, chaque musicien sa partition. En séparant les responsabilités, on obtient un code plus lisible, plus testable, plus évolutif.
+
+**Exemple :**
+
+```java
+// Mauvais exemple : une classe fait tout
+class Application {
+    void afficherUI() {}
+    void sauvegarderDonnees() {}
+    void envoyerEmail() {}
+}
+
+// Bon exemple : séparation des responsabilités
+class UIManager { void afficherUI() {} }
+class DataManager { void sauvegarderDonnees() {} }
+class EmailService { void envoyerEmail() {} }
+```
+
+Chaque classe, chaque module, doit avoir une mission claire et limitée.
+
+
+## Encapsulation
+
+L’encapsulation, c’est l’art de protéger les secrets de fabrication. En cachant les détails internes d’une classe, on limite les risques d’erreur et on rend le code plus robuste face aux changements.
+
+**Exemple :**
+
+```java
+// Mauvais exemple : attributs publics
+class Compte {
+    public double solde;
+}
+
+// Bon exemple : attribut privé et méthodes d’accès
+class Compte {
+    private double solde;
+    public double getSolde() { return solde; }
+    public void deposer(double montant) { solde += montant; }
+}
+```
+
+L’utilisateur de la classe n’a accès qu’à ce qui est nécessaire, et rien de plus.
+
+
+## Information Hiding (Masquage d’information)
+
+Proche de l’encapsulation, le masquage d’information vise à limiter l’exposition des détails d’implémentation. Moins on en montre, moins on risque de devoir tout changer si l’intérieur évolue.
+
+**Exemple :**
+
+```java
+// Mauvais exemple : exposer la structure interne
+class Stack {
+    public Object[] elements;
+}
+
+// Bon exemple : masquer la structure
+class Stack {
+    private Object[] elements;
+    public void push(Object o) { /* ... */ }
+    public Object pop() { /* ... */ }
+}
+```
+
+
+## Composition Over Inheritance (Préférer la composition à l’héritage)
+
+L’héritage est parfois tentant, mais il peut rendre le code rigide et difficile à faire évoluer. La composition, elle, offre souplesse et modularité. En assemblant des objets, on construit des systèmes plus adaptables.
+
+**Exemple :**
+
+Imaginons que l’on souhaite modéliser des périphériques bureautiques : certaines imprimantes peuvent aussi scanner ou faxer, d’autres non. Si l’on utilise l’héritage, on se retrouve vite avec une hiérarchie complexe et peu flexible. La composition permet d’assembler dynamiquement les fonctionnalités nécessaires.
+
+```java
+// Mauvais exemple : héritage rigide
+class Imprimante {
+    void imprimer() {}
+}
+class ImprimanteMultifonction extends Imprimante {
+    void scanner() {}
+    void faxer() {}
+}
+
+// Bon exemple : composition flexible
+interface Scanner {
+    void scanner();
+}
+interface Fax {
+    void faxer();
+}
+class Imprimante {
+    void imprimer() {}
+}
+class ImprimanteMultifonction {
+    private Imprimante imprimante;
+    private Scanner scanner;
+    private Fax fax;
+    ImprimanteMultifonction(Imprimante imprimante, Scanner scanner, Fax fax) {
+        this.imprimante = imprimante;
+        this.scanner = scanner;
+        this.fax = fax;
+    }
+    void imprimer() { imprimante.imprimer(); }
+    void scanner() { scanner.scanner(); }
+    void faxer() { fax.faxer(); }
+}
+```
+
+Avec la composition, on peut créer des objets multifonctions ou spécialisés sans multiplier les sous-classes, et faire évoluer les fonctionnalités indépendamment les unes des autres.

docs/cours/genie-logiciel/robustesse-et-erreurs.md

@@ -0,0 +1,34 @@
+# Robustesse et gestion des erreurs
+
+Dans le monde du développement logiciel, la robustesse n’est pas un luxe, mais une nécessité. Un programme robuste est celui qui résiste aux imprévus, qui ne s’effondre pas au premier grain de sable dans les rouages. La gestion des erreurs, loin d’être une simple formalité, est un art subtil qui distingue l’amateur du professionnel. Parmi les principes fondamentaux, le « Fail Fast » occupe une place de choix.
+
+## Fail Fast
+
+Imaginez un navire dont l’équipage détecte immédiatement la moindre voie d’eau, plutôt que de laisser l’eau s’infiltrer silencieusement jusqu’au naufrage. Le principe « Fail Fast » invite le développeur à signaler toute anomalie dès qu’elle survient, sans attendre que le problème se propage et devienne inextricable.
+
+Détecter tôt, c’est se donner la chance de corriger vite. Un code qui échoue rapidement est plus facile à déboguer, plus sûr, et inspire confiance à ceux qui l’utilisent ou le maintiennent.
+
+**Exemple :**
+
+```java
+// Mauvais exemple : ignorer les erreurs
+public void traiter(String fichier) {
+    try {
+        // ...
+    } catch (Exception e) {
+        // rien faire
+    }
+}
+
+// Bon exemple : signaler l’erreur immédiatement
+public void traiter(String fichier) {
+    if (fichier == null) {
+        throw new IllegalArgumentException("Le fichier ne peut pas être null");
+    }
+    // ...
+}
+```
+
+Dans le premier cas, l’erreur est étouffée, masquée, et le programme continue sa route en terrain miné. Dans le second, l’exception est levée sans délai, permettant une réaction rapide et appropriée.
+
+La robustesse, c’est aussi le courage de dire « stop » quand quelque chose ne va pas, plutôt que de laisser le système s’enfoncer dans l’incohérence. Adopter le « Fail Fast », c’est choisir la transparence, la sécurité, et la qualité.