# 🧭 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**