Galactic-Shrine Coding Standard

Version: 1.0.0
Auteur / Author: ⋞Galactic-Shrine⋟
Portée / Scope: Standards transversaux / Bibliothèques / Frameworks / SDKs / Applications / Services / APIs / Outils internes / Produits Galactic-Shrine

1. Objectif

Ce standard définit les conventions de codage transversales applicables dans les projets Galactic-Shrine.

Il a pour objectifs :

d’uniformiser l’écriture du code entre les langages ;
d’améliorer la lisibilité, la maintenabilité et la relecture ;
de réduire les divergences de style entre projets et contributeurs ;
de fixer les règles de nommage, de structure et de robustesse ;
de fournir une base commune avant les standards spécifiques par langage.

2. Principes fondamentaux

Le code Galactic-Shrine doit être :

clair ;
cohérent ;
explicite ;
maintenable ;
robuste ;
raisonnablement extensible.

Le code doit privilégier :

la lisibilité avant l’astuce ;
la cohérence avant les préférences individuelles ;
des responsabilités courtes et bien délimitées ;
des noms explicites ;
des contrats d’entrée et de sortie compréhensibles ;
des structures simples à relire.

3. Décisions transversales officielles

Décisions officielles Galactic-Shrine applicables par défaut :

les propriétés doivent être en PascalCase ;
les paramètres doivent être en PascalCase ;
les méthodes / fonctions doivent être en PascalCase ;
les types doivent être en PascalCase ;
les constantes nommées doivent être en PascalCase, sauf contrainte forte du langage ou d’un standard externe ;
les abréviations doivent rester lisibles et stables (HttpClient, XmlWriter, UuidValue) ;
un nom doit décrire l’intention, pas seulement l’implémentation.

Règle d’exception :

Une convention imposée par un framework, une API externe, une sérialisation, une interopérabilité, un standard public ou un langage peut justifier une dérogation locale.
Dans ce cas, la dérogation doit rester ciblée, explicite et techniquement justifiée.

4. Convention de nommage globale

4.1 Types

classes : PascalCase
interfaces : préfixe propre au langage si nécessaire, sinon PascalCase
structures / structs : PascalCase
enums : PascalCase
namespaces / packages / modules : selon les usages du langage, mais de manière stable et prévisible

4.2 Membres

propriétés : PascalCase
méthodes : PascalCase
paramètres : PascalCase
événements : PascalCase
champs privés : convention locale du langage, mais cohérente dans tout le projet
variables locales : convention locale du langage, mais éviter les formes ambiguës ou cryptiques

4.3 Fichiers et dossiers

un nom de fichier doit refléter clairement le contenu principal ;
éviter les noms vagues comme Helper, Utils, Common, Misc sans qualification ;
préférer des regroupements fonctionnels clairs plutôt qu’un rangement opportuniste.

5. Structure des fichiers

Chaque fichier doit tendre vers une structure simple et prévisible.

Ordre recommandé lorsque le langage le permet :

en-tête légal ou technique si requis ;
déclarations globales (namespace, module, use, import, include) ;
types, fonctions ou constantes publics principaux ;
implémentations privées ou détails internes ;
éventuels helpers strictement liés au fichier.

Règles générales :

un fichier doit avoir une responsabilité identifiable ;
éviter de mélanger API publique, logique métier et utilitaires génériques sans lien ;
éviter les fichiers “fourre-tout”.

6. Règles de style

6.1 Lisibilité

préférer des blocs courts ;
réduire l’imbrication quand un retour anticipé améliore la lecture ;
éviter les expressions trop compactes si elles nuisent à la compréhension ;
garder un style stable sur tout le projet.

6.2 Conditions

une condition doit exprimer une intention claire ;
éviter les doubles négations ;
extraire une variable nommée lorsque l’expression devient difficile à lire ;
documenter les cas métier non évidents.

6.3 Commentaires

commenter le pourquoi et le contrat, pas chaque ligne évidente ;
éviter les commentaires qui répètent exactement le nom de la méthode ;
conserver une cohérence avec les standards de documentation Galactic-Shrine.

6.4 Données temporaires

limiter la durée de vie des variables locales ;
éviter les mutations inutiles ;
rapprocher la déclaration de l’usage réel.

7. Architecture locale

Le code Galactic-Shrine doit éviter :

les classes ou modules “dieu” ;
les helpers génériques sans périmètre clair ;
les méthodes longues qui mélangent plusieurs responsabilités ;
les dépendances implicites difficiles à tracer ;
les effets de bord cachés.

Le code doit favoriser :

une responsabilité par type ou fonction principale ;
des dépendances explicites ;
une séparation nette entre orchestration, logique métier et accès technique ;
des noms de types orientés intention (Service, Provider, Factory, Builder, Repository, Mapper, Validator, Options, Result, selon le langage et le besoin réel).

8. Validation, erreurs et nullabilité

Règles générales :

valider les entrées aux frontières importantes ;
échouer tôt sur les données invalides ;
distinguer autant que possible erreur métier, erreur technique et absence de donnée ;
ne pas masquer silencieusement une erreur importante ;
produire des messages d’erreur utiles au diagnostic.

La nullabilité doit être traitée explicitement :

accepter null uniquement si cela a du sens dans le contrat ;
éviter les valeurs sentinelles ambiguës ;
documenter les cas optionnels.

9. Sécurité, performance et compatibilité

Le code doit :

éviter les concaténations non sûres pour les requêtes, chemins, commandes ou expressions évaluées ;
normaliser et valider les entrées externes ;
éviter l’exposition involontaire de données sensibles dans les logs ;
viser une performance raisonnable sans sacrifier la lisibilité prématurément ;
rester compatible avec les contraintes de la plateforme cible.

Règle :

Ne pas optimiser spéculativement.
Optimiser les zones identifiées comme coûteuses, mesurées ou critiques.

10. Exceptions au standard

Une exception au standard est acceptable si :

elle répond à une contrainte réelle du langage ou du framework ;
elle améliore clairement l’interopérabilité ;
elle évite une complexité artificielle ;
elle reste locale et documentée.

Une exception n’est pas acceptable si :

elle repose seulement sur une préférence personnelle ;
elle crée deux styles concurrents dans le même projet ;
elle réduit la lisibilité générale ;
elle affaiblit le contrat de code.

11. Décision officielle recommandée

Standard officiel recommandé pour Galactic-Shrine Coding :

imposer PascalCase pour propriétés, paramètres et méthodes ;
garder des noms explicites et stables ;
structurer les fichiers et les responsabilités de manière prévisible ;
limiter la taille et la complexité des blocs ;
valider les entrées importantes ;
documenter les dérogations imposées par l’écosystème ;
conserver une cohérence stricte à l’échelle du dépôt.

12. Résumé exécutable

À appliquer dans tous les projets Galactic-Shrine :

écrire un code clair, stable et relisible ;
utiliser PascalCase pour propriétés, paramètres et méthodes ;
éviter les fichiers et types “fourre-tout” ;
préférer des responsabilités courtes ;
valider les entrées et traiter les erreurs explicitement ;
ne déroger au standard que pour une raison technique réelle.