# Galactic-Shrine C# Documentation Standard
**Version:** 1.2.0
**Auteur / Author:** ⋞Galactic-Shrine⋟
**Portée / Scope:** Projets C# / .NET / Bibliothèques / Applications Console / WinForms / WPF / ASP.NET / Outils internes
---
## 1. Objectif
Ce standard définit la manière de documenter le code **C#** dans les projets Galactic-Shrine.
Il a pour objectifs :
- d’uniformiser la documentation du code ;
- de conserver un style bilingue `[FR] / [EN]` ;
- de rester cohérent avec la convention documentaire Galactic-Shrine ;
- de conserver une structure visuelle homogène ;
- de documenter proprement les types et membres importants.
---
## 2. Principes généraux
La documentation C# Galactic-Shrine doit être :
- claire ;
- concise ;
- bilingue ;
- contractuelle ;
- utile techniquement.
La documentation doit privilégier :
- le format documentaire XML utilisé dans le standard Galactic-Shrine ;
- les descriptions courtes ;
- les balises XML utiles au contrat public ;
- les explications techniques réelles, sans surdocumentation.
---
## 3. Format obligatoire des blocs
Toujours utiliser le format suivant :
```csharp
/**
*
* [FR] Génère les fichiers de traduction.
* [EN] Generates translation files.
*
**/
```
Ce format constitue le standard officiel recommandé pour Galactic-Shrine C#.
---
## 4. Convention bilingue
Chaque balise descriptive doit suivre l’ordre suivant :
1. ligne française `[FR]`
2. ligne anglaise `[EN]`
Exemple :
```csharp
/**
*
* [FR] Recherche un fichier de configuration.
* [EN] Searches for a configuration file.
*
**/
```
---
## 5. Éléments autorisés
Éléments autorisés dans les commentaires C# Galactic-Shrine :
- texte libre avec `[FR]` et `[EN]`
- ``
- ``
- ``
- ``
- ``
- ``
- ``
- ``
- ``
Éléments déconseillés :
- les descriptions longues sans valeur contractuelle ;
- les balises inutiles sur du code trivial ;
- les commentaires redondants avec le nom du membre sans contexte supplémentaire.
---
## 6. Structure recommandée d’un commentaire
Ordre recommandé :
1. ``
2. `` si nécessaire
3. `` pour chaque paramètre générique
4. `` pour chaque paramètre
5. `` si une valeur est retournée
6. `` si l’exception fait partie du contrat
7. `` pour une propriété lorsque cela apporte une vraie valeur
8. autres balises utiles (``, ``)
Exemple :
```csharp
/**
*
* [FR] Convertit une valeur brute en locale normalisée.
* [EN] Converts a raw value into a normalized locale.
*
*
* [FR] Valeur d’entrée à convertir.
* [EN] Input value to convert.
*
*
* [FR] La locale normalisée.
* [EN] The normalized locale.
*
**/
```
---
## 7. Standard par type d’élément
### 7.1 Classe
```csharp
/**
*
* [FR] Représente un générateur de traductions YAML.
* [EN] Represents a YAML translation generator.
*
*
* [FR] Ce composant centralise la normalisation des locales,
* la collecte des clés et l’écriture des fichiers.
* [EN] This component centralizes locale normalization,
* key collection, and file writing.
*
**/
public sealed class TranslationGenerator
{
}
```
### 7.2 Interface
```csharp
/**
*
* [FR] Définit le contrat d’un générateur de traductions.
* [EN] Defines the contract of a translation generator.
*
**/
public interface ITranslationGenerator
{
}
```
### 7.3 Enum
```csharp
/**
*
* [FR] Représente le niveau de journalisation.
* [EN] Represents the logging level.
*
**/
public enum LogLevel
{
/**
*
* [FR] Information générale.
* [EN] General information.
*
**/
Information,
/**
*
* [FR] Avertissement.
* [EN] Warning.
*
**/
Warning
}
```
### 7.4 Propriété
```csharp
/**
*
* [FR] Obtient ou définit la locale active.
* [EN] Gets or sets the active locale.
*
*
* [FR] Une valeur normalisée, par exemple fr ou en.
* [EN] A normalized value, for example fr or en.
*
**/
public string Locale { get; set; } = "fr";
```
### 7.5 Constructeur
```csharp
/**
*
* [FR] Initialise une nouvelle instance de la classe .
* [EN] Initializes a new instance of the class.
*
*
* [FR] Chemin racine du projet.
* [EN] Project root path.
*
**/
public TranslationGenerator(string projectDirectory)
{
}
```
### 7.6 Méthode
```csharp
/**
*
* [FR] Normalise une liste de locales.
* [EN] Normalizes a list of locales.
*
*
* [FR] Valeurs d’entrée à normaliser.
* [EN] Input values to normalize.
*
*
* [FR] Une liste de locales normalisées.
* [EN] A list of normalized locales.
*
**/
public IReadOnlyList NormalizeLocales(IEnumerable? locales)
{
}
```
### 7.7 Méthode générique
```csharp
/**
*
* [FR] Convertit une valeur vers un type cible.
* [EN] Converts a value to a target type.
*
*
* [FR] Type cible de conversion.
* [EN] Target conversion type.
*
*
* [FR] Valeur à convertir.
* [EN] Value to convert.
*
*
* [FR] La valeur convertie.
* [EN] The converted value.
*
**/
public static T ConvertTo(object? value)
{
}
```
### 7.8 Méthode avec exception
```csharp
/**
*
* [FR] Charge le contenu d’un fichier YAML.
* [EN] Loads the content of a YAML file.
*
*
* [FR] Chemin du fichier à charger.
* [EN] Path of the file to load.
*
*
* [FR] Le contenu du fichier.
* [EN] The file content.
*
*
* [FR] Levée lorsque le chemin est vide.
* [EN] Thrown when the path is empty.
*
**/
public string LoadFile(string filePath)
{
}
```
---
## 8. Règles de style
### 8.1 Descriptions courtes
Toujours préférer une phrase simple et directe.
### 8.2 Ordre fixe
Toujours écrire `[FR]` avant `[EN]`.
### 8.3 Indentation recommandée
Conserver exactement l’indentation du modèle officiel.
### 8.4 ``
Utiliser `` uniquement si un complément utile existe.
### 8.5 ``
Toujours documenter `` lorsqu’une méthode retourne une valeur.
### 8.6 ``
N’ajouter `` que si l’exception est réellement importante dans le contrat de la méthode.
### 8.7 Pas de surdocumentation
Ne pas commenter l’évidence.
---
## 9. Types d’éléments à documenter en priorité
Documenter en priorité :
- classes publiques ;
- interfaces ;
- structs publiques ;
- enums ;
- méthodes publiques ;
- propriétés publiques ;
- événements publics ;
- méthodes génériques ;
- points d’extension ;
- API internes complexes.
---
## 10. Exemple complet recommandé
```csharp
namespace GalacticShrine.Localization;
/**
*
* [FR] Représente un générateur de traductions YAML.
* [EN] Represents a YAML translation generator.
*
*
* [FR] Ce composant centralise la normalisation des locales,
* la collecte des clés et l’écriture des fichiers de sortie.
* [EN] This component centralizes locale normalization,
* key collection, and output file writing.
*
**/
public sealed class TranslationGenerator
{
/**
*
* [FR] Obtient le répertoire racine du projet.
* [EN] Gets the project root directory.
*
**/
public string ProjectDirectory { get; }
/**
*
* [FR] Initialise une nouvelle instance de la classe .
* [EN] Initializes a new instance of the class.
*
*
* [FR] Chemin racine du projet.
* [EN] Project root path.
*
**/
public TranslationGenerator(string projectDirectory)
{
ProjectDirectory = projectDirectory;
}
/**
*
* [FR] Normalise une liste de locales.
* [EN] Normalizes a list of locales.
*
*
* [FR] Valeurs d’entrée à normaliser.
* [EN] Input values to normalize.
*
*
* [FR] Une liste de locales normalisées.
* [EN] A list of normalized locales.
*
**/
public IReadOnlyList NormalizeLocales(IEnumerable? locales)
{
return Array.Empty();
}
}
```
---
## 11. Décision officielle recommandée
Standard officiel recommandé pour Galactic-Shrine C# :
- utiliser le bloc `/** ... **/` ;
- utiliser `` pour la description principale ;
- écrire d’abord `[FR]`, puis `[EN]` ;
- utiliser ``, ``, ``, ``, ``, `` quand nécessaire ;
- documenter ce qui compte, pas l’évidence ;
- conserver une mise en forme stricte et homogène.
---
## 12. Résumé exécutable
À appliquer dans tous les projets C# Galactic-Shrine :
- utiliser le format XML documentaire Galactic-Shrine ;
- écrire `[FR]` puis `[EN]` dans chaque balise descriptive ;
- documenter les types publics, membres publics et API complexes ;
- garder un style court, propre et uniforme ;
- éviter les commentaires inutiles sur le code trivial.