multi_render_blender/Norme.md

🧭 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 :

let nb_chats = 5;
let list_chats = [];
let is_chat = true;

❌ Incorrect :

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 :

class User {}
class Project {}

❌ Incorrect :

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 :

function main() {
    let compteur = 0;
    let message = "Hello";
    console.log(message);
}

❌ Incorrect :

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 :

let str_nom = "Jean";
let list_ids = [];

❌ Incorrect :

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 :

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 :

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 :

nb_chats = 5
list_chats = []
is_chat = True
str_nom = "Jean"

❌ Incorrect :

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 :

   for (let user of list_users) {
       traiter_utilisateur(user);
   }
   

   ❌ Incorrect :

   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