Galactic-Shrine JavaScript Coding Standard

Version: 1.0.0
Auteur / Author: ⋞Galactic-Shrine⋟
Portée / Scope: Projets JavaScript / ES Modules / Browser / Node.js / Tooling / Front-end / Back-end / Scripts / Components

1. Objectif

Ce standard définit la manière d’écrire le code JavaScript dans les projets Galactic-Shrine.

Il a pour objectifs :

• d’uniformiser le style JavaScript ;
• de conserver une base lisible malgré la souplesse du langage ;
• d’aligner le nommage avec la convention Galactic-Shrine ;
• de réduire les zones implicites et ambiguës.

2. Principes généraux

Le code JavaScript Galactic-Shrine doit être :

• explicite ;
• stable ;
• lisible ;
• prudent vis-à-vis de l’implicite ;
• structuré selon le runtime visé.

Le code doit privilégier :

• des modules petits et ciblés ;
• des noms explicites ;
• des fonctions courtes ;
• des transformations de données lisibles ;
• une séparation claire entre DOM, logique métier et intégrations.

3. Décisions officielles Galactic-Shrine pour JavaScript

Décisions officielles :

• classes : PascalCase ;
• méthodes : PascalCase ;
• paramètres : PascalCase ;
• propriétés d’objets applicatifs internes : PascalCase lorsque le contrat est maîtrisé ;
• variables locales : PascalCase ;
• constantes de module : PascalCase ;
• fichiers de modules : nom cohérent avec la responsabilité ;
• fonctions asynchrones suffixées par Async lorsque cela améliore la clarté.

Règle d’exception :

Les objets JSON, APIs publiques web, conventions DOM, noms d’options imposés par une bibliothèque ou formats externes peuvent conserver leur convention native.

4. Convention de nommage

• classe : PascalCase ;
• méthode : PascalCase ;
• paramètre : PascalCase ;
• variable locale : PascalCase ;
• constante : PascalCase ;
• événement ou handler interne : explicite, orienté intention ;
• nom de module : clair et ciblé.

À éviter :

• data, item, obj, el, tmp répétés sans contexte ;
• les noms qui cachent une mutation ou un effet de bord ;
• les fonctions “helpers” énormes.

5. Structure recommandée d’un module JavaScript

Ordre recommandé :

1. imports ;
2. constantes locales ;
3. types ou classes locales si besoin ;
4. fonction ou classe principale exportée ;
5. helpers privés strictement liés au module.

Règles :

• un module doit avoir une responsabilité identifiable ;
• limiter le nombre d’exports si cela brouille le rôle du fichier ;
• éviter de mélanger orchestration UI et logique de transformation profonde.

6. Style d’écriture

6.1 Déclarations

• préférer const puis let ;
• éviter var ;
• rapprocher la déclaration de l’usage.

6.2 Fonctions

• préférer des fonctions nommées pour la logique importante ;
• garder les callbacks courts ;
• éviter les chaînes de transformations illisibles.

6.3 async/await

• préférer async/await à des chaînes de then complexes ;
• gérer les erreurs explicitement ;
• éviter les appels parallèles non maîtrisés.

6.4 Conditions

• rendre les tests lisibles ;
• éviter les coercitions surprenantes ;
• utiliser === et !== par défaut.

7. Règles spécifiques JavaScript

• ne pas dépendre d’un état global caché ;
• encapsuler l’accès au DOM complexe ;
• isoler les appels réseau ;
• valider les entrées externes ou événements transformés ;
• éviter les objets polymorphes sans contrat ;
• limiter la métaprogrammation et les patterns trop abstraits si le gain est faible.

8. Gestion des erreurs et robustesse

• lever ou propager une erreur exploitable ;
• ne pas masquer un échec de requête ;
• distinguer les erreurs attendues des défauts techniques ;
• renvoyer des structures de résultat stables si le flux l’exige ;
• journaliser avec discernement.

9. Types d’éléments à revoir en priorité

Relire en priorité :

• modules réseau ;
• services front-end ;
• composants riches en état ;
• gestionnaires d’événements complexes ;
• adaptateurs d’APIs externes ;
• code de transformation JSON ;
• scripts de build ou tooling critiques.

10. Exemple complet recommandé

export class UserProfileService {
    constructor(ApiClient) {
        this.ApiClient = ApiClient;
    }

    async UpdateDisplayNameAsync(UserId, DisplayName) {
        const NormalizedDisplayName = DisplayName.trim();

        if (NormalizedDisplayName.length === 0) {
            return { IsSuccess: false, ErrorCode: "EmptyDisplayName" };
        }

        const Response = await this.ApiClient.PostAsync("/users/display-name", {
            userId: UserId,
            displayName: NormalizedDisplayName,
        });

        if (!Response.ok) {
            return { IsSuccess: false, ErrorCode: "RequestFailed" };
        }

        return { IsSuccess: true };
    }
}

11. Décision officielle recommandée

Standard officiel recommandé pour Galactic-Shrine JavaScript :

• utiliser PascalCase pour méthodes, paramètres et variables locales ;
• appliquer PascalCase aux propriétés internes quand le contrat t’appartient ;
• conserver les conventions externes quand l’interopérabilité l’exige ;
• écrire des modules courts, avec responsabilités nettes ;
• éviter l’implicite fragile.

12. Résumé exécutable

À appliquer dans tous les projets JavaScript Galactic-Shrine :

• PascalCase pour méthodes, paramètres et variables locales ;
• const par défaut ;
• async/await propre ;
• modules ciblés ;
• validation des entrées externes ;
• exceptions ciblées pour les conventions JSON ou APIs externes.