v1

Norme.md

@@ -0,0 +1,325 @@
+# 🧭 Norme de Développement
+
+*Version 2.0 – Pour IA et nouveaux collaborateurs*
+
+---
+
+## 🧠 Philosophie de développement
+
+Le but de cette norme est de garantir un code **clair, cohérent et maintenable**, que ce soit par un développeur humain ou une IA d’assistance.
+Chaque ligne doit être **compréhensible au premier regard**, chaque fonction doit **faire une seule chose**, et la structure du projet doit **rester intuitive** sans dépendre de frameworks lourds ou de bibliothèques inutiles.
+
+---
+
+## 🧩 Structure générale
+
+* Le code doit rester **simple, explicite et lisible**.
+* On privilégie la **cohérence** à la créativité syntaxique.
+* Le code doit être **autoportant** : bien nommé plutôt que sur-commenté.
+* Le style doit être uniforme entre tous les fichiers.
+
+---
+
+## 🐍 Nommage
+
+### Variables
+
+* Toujours en **snake_case** : `ma_variable`, `list_users`, `is_valid`.
+* Pas de chiffres dans les noms.
+* Le nom doit **refléter le rôle et le type** de la donnée.
+* Préfixes recommandés :
+
+  * `nb_` → quantité (ex: `nb_utilisateurs`)
+  * `is_` / `has_` → booléen (ex: `is_active`, `has_error`)
+  * `list_` → tableau ou collection
+  * `str_` → chaîne de caractères
+  * `obj_` → objet ou structure complexe
+
+✅ **Correct :**
+
+```js
+let nb_chats = 5;
+let list_chats = [];
+let is_chat = true;
+```
+
+❌ **Incorrect :**
+
+```js
+let 1chien = 1;
+let mechantChien = {};
+let IS_CHIEN = false;
+let nb_chien = new Chien();
+```
+
+---
+
+### Classes / Structures
+
+* Une majuscule au début (`User`, `Project`).
+* Un seul mot.
+* Si plusieurs concepts sont nécessaires, utiliser une **composition**, pas un nom long.
+
+✅ **Correct :**
+
+```js
+class User {}
+class Project {}
+```
+
+❌ **Incorrect :**
+
+```js
+class user {}
+class ProjectNuageDePoints {}
+```
+
+---
+
+## 🧱 Structure du code
+
+### Déclaration des variables
+
+Toutes les variables doivent être **déclarées en début de fonction**, avant toute action logique.
+
+✅ **Correct :**
+
+```js
+function main() {
+    let compteur = 0;
+    let message = "Hello";
+    console.log(message);
+}
+```
+
+❌ **Incorrect :**
+
+```js
+function main() {
+    console.log("test");
+    let compteur = 0;
+}
+```
+
+---
+
+### Typage implicite et explicite
+
+* Si le type est évident, inutile de le préciser.
+* Sinon, indiquer le type clairement.
+
+✅ **Correct :**
+
+```js
+let str_nom = "Jean";
+let list_ids = [];
+```
+
+❌ **Incorrect :**
+
+```js
+let x;
+```
+
+---
+
+### Placement des crochets
+
+Le premier `{` doit toujours être **sur la même ligne** que l’instruction.
+
+---
+
+## ⚙️ Promesses et gestion asynchrone (JavaScript)
+
+### Interdiction de `async/await`
+
+* `async` / `await` sont **strictement interdits**.
+* Toujours utiliser des chaînes `.then()` / `.catch()`.
+
+✅ **Correct :**
+
+```js
+action_async()
+    .then((data) => {
+        return sous_action_async(data);
+    })
+    .then((result) => {
+        utiliser_resultat(result);
+    })
+    .catch((err) => {
+        afficher_message_utilisateur("Une erreur est survenue.");
+        console.error(err);
+    });
+```
+
+❌ **Incorrect :**
+
+```js
+async function main() {}
+```
+
+---
+
+## 🧠 Bonnes pratiques générales
+
+* Une **fonction = une responsabilité unique**.
+* Extraire toute logique répétée dans une fonction utilitaire.
+* Les noms de fonctions doivent décrire précisément leur action.
+* Pas de code commenté laissé dans le projet.
+* Les fonctions doivent tenir **dans la hauteur visible d’un écran**.
+
+---
+
+## 🧩 Style de code
+
+* **Indentation :** 4 espaces.
+* **Point-virgule :** obligatoire.
+* **Fonctions fléchées** toujours préférées.
+* **Constantes globales** en MAJUSCULES.
+
+---
+
+## 🧩 Organisation des fichiers
+
+* Fichiers JS en **PascalCase**.
+* Fichiers Python en **snake_case**.
+* Pas de framework structurant lourd.
+* HTML / CSS / JS natif privilégié.
+
+---
+
+## 🐍 Règles spécifiques Python
+
+* **Type hints** obligatoires sur toutes les signatures de fonctions.
+* **Docstrings** en français sur toutes les fonctions publiques.
+* Imports regroupés en haut du fichier, dans l'ordre :
+  1. Bibliothèque standard
+  2. Bibliothèques tierces
+  3. Modules du projet
+* Gestion d'erreurs : tout `try/except` doit loguer l'erreur ET la remonter.
+* Pas de `print()` en production, utiliser le module `logging`.
+* Les constantes globales sont en **MAJUSCULES**.
+* Les variables suivent les mêmes règles de préfixage que JavaScript
+  (`nb_`, `is_`, `has_`, `list_`, `str_`, `obj_`).
+
+✅ **Correct :**
+
+```python
+nb_chats = 5
+list_chats = []
+is_chat = True
+str_nom = "Jean"
+```
+
+❌ **Incorrect :**
+
+```python
+chats = 5
+mechantChien = {}
+IS_CHIEN = False
+nb_chien = Chien()
+```
+
+---
+
+## 💬 Commentaires et documentation
+
+* Commentaires rares et utiles uniquement.
+* Pas de JSDoc obligatoire.
+* Commentaires en anglais simple si nécessaires.
+
+---
+
+## 🧱 Gestion des erreurs
+
+* Toujours afficher une **erreur utilisateur visible**.
+* Les erreurs techniques doivent être **loguées**.
+* Aucune erreur ne doit être ignorée silencieusement.
+
+---
+
+## 🧩 Git et gestion de versions
+
+* Un commit = une fonctionnalité complète.
+* Aucun commit cassé ou incomplet.
+
+---
+
+## ⚙️ Outils et dépendances
+
+* Dépendances externes **fortement limitées**.
+* Aucun framework JS lourd.
+* Backend en **Python** avec **Flask** (léger, sans ORM).
+* **Exceptions autorisées pour le frontend** :
+  * **Bootstrap 5** (CSS + JS) via CDN pour la mise en page et les composants UI.
+  * **Material Design Icons (MDI)** via CDN pour les icônes.
+
+---
+
+## 🤖 Règles spécifiques pour l’assistant IA
+
+L’IA d’assistance au développement doit :
+
+1. **Ne jamais utiliser `async/await`.**
+   Toujours préférer `.then()` / `.catch()` avec retour de promesse.
+
+2. **Ne jamais utiliser `forEach()`.**
+
+   * L’itération sur des tableaux ou collections doit obligatoirement utiliser des boucles `for...of`.
+   * Cette règle garantit :
+
+     * un meilleur contrôle du flux (`break`, `continue`, `return`),
+     * une lisibilité accrue,
+     * une cohérence avec les règles de débogage et de responsabilité.
+
+   ✅ **Correct :**
+
+   ```js
+   for (let user of list_users) {
+       traiter_utilisateur(user);
+   }
+   ```
+
+   ❌ **Incorrect :**
+
+   ```js
+   list_users.forEach((user) => {
+       traiter_utilisateur(user);
+   });
+   ```
+
+3. **Reformater automatiquement** le code selon cette norme.
+
+4. **Vérifier la lisibilité et la cohérence** avant toute proposition.
+
+5. **Proposer des refactorings** en cas de duplication.
+
+6. **Créer des fonctions utilitaires** si une logique se répète.
+
+7. **Respecter strictement le nommage** (`snake_case`, `PascalCase`).
+
+8. **Toujours gérer les erreurs** avec un `.catch()` visible utilisateur.
+
+9. **Ne pas utiliser de dépendances externes** sans valeur fonctionnelle claire.
+
+10. **En Python, toujours utiliser des type hints** sur les paramètres et retours de fonctions.
+
+11. **En Python, toujours inclure une docstring** sur les fonctions publiques.
+
+12. **Ne jamais utiliser `print()` pour le logging** ; utiliser le module `logging`.
+
+13. **Appliquer les mêmes préfixes de variables** en Python qu'en JavaScript.
+
+---
+
+## 📘 Conclusion
+
+Ce document est une **référence de cohérence globale** pour le projet.
+Il s’applique **aux humains comme à l’IA**.
+
+Le code doit rester :
+
+* **Lisible**
+* **Prévisible**
+* **Maintenable**
+* **Humain**