326 lines
7.2 KiB
Markdown
326 lines
7.2 KiB
Markdown
# 🧭 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**
|