Angular Guideline

Les guidelines présentées dans ce document suivent les bonnes pratiques Angular et visent à améliorer la lisibilité, la maintenabilité et la cohérence du code au sein des équipes.
Ces conventions s’inspirent des standards officiels Angular ainsi que de règles internes établies pour un code plus clair, plus efficace et plus structuré.

Règles de Formatage

Programmation

Programmez en anglais. Privilégiez des identifiants explicites et évitez les abréviations.

Indentation

Utilisez une indentation de 4 espaces.
N'utilisez pas de tabulations.
Indentez rigoureusement votre code pour en améliorer la lisibilité.

Mise en page

Adoptez un style de mise en page cohérent et privilégiez la clarté dans vos fichiers. Regroupez logiquement votre code et aérez-le pour en faciliter la lecture.

Longueur de ligne & Taille de fichier

Limitez la longueur des lignes à 120 caractères maximum.
Ne dépassez pas 400 lignes par fichier pour conserver une organisation claire.

Commentaires

Ecrivez les commentaires en anglais.

Laissez un espace après le délimiteur de commentaire. Par exemple : // Explains a business rule

Les commentaires doivent expliquer le pourquoi, jamais le quoi. Utilisez-les pour clarifier les choix techniques, les spécificités métier, ou les raisons d’un contournement, mais pas pour décrire ce qui est déjà explicite dans le code.

Imports & Organisation

Utilisez l’organisation automatique des imports (organize imports on save).
Triez et nettoyez les imports régulièrement.
N’introduisez pas d’imports non utilisés.
Privilégiez les imports par chemin absolu.
Si nécessaire, définissez des alias pour les imports répétitifs.

Conventions de Nommage

Identifiant Case Exemple
Classe / Composant / Service / Directive / Pipe PascalCase 
// Example
export class ProductListComponent {
    // Insert code here
}
Interface (API model) PascalCase (pas de préfixe "I") 
// Example
export interface ProductApi {
    id: number;
    name: string;
}
Type (Alias interne) PascalCase 
// Example
export type ProductDetail = {
    id: number;
    description: string;
};
Enum (API) PascalCase (enum + valeurs) 
// Example
export enum OrderStatusApi {
    Pending,
    Shipped,
    Delivered
}
Fonction / Méthode camelCase 
// Examples
function computeTotal(price: number, quantity: number): number {
    return price * quantity;
}

class OrderService {
    fetchOrders() {
        // Insert code here
    }
}
Propriété / Champ / Variable Locale / Paramètre camelCase 
// Examples
const pageSize = 20;

class Product {
    constructor(private name: string, private price: number) {}

    getName() { return this.name; }
    getPrice() { return this.price; }
}
Champ Privé avec Identifiant Privé # + camelCase 
// Example
class ProductComponent {
    #internalCounter = 0;

    increment() {
        this.#internalCounter++;
    }
}
Constante Globale CONSTANT_CASE 
// Example
const MAX_ITEMS = 100;

Noms des Fichiers

Suivez les conventions de nommage Angular en suffixant le type de fichier (.component, .service, .resolver, etc.).
Utilisez le kebab-case pour nommer les fichiers.
Le nom du fichier doit refléter le contenu, par exemple : product-list.component.ts.

Noms des Composants

Les classes de composants Angular utilisent le PascalCase (ex: ProductListComponent).
Pour les composants complexes, utilisez le schéma component-subcomponent-subsubcomponent.
Par exemple : list, list-item, list-item-header.

Noms des Services

Les classes de services Angular utilisent également le PascalCase (ex: ProductApiService).
Les services d’appel HTTP vers l’API doivent avoir le suffixe ApiService.

Noms des Modèles (API / Application)

Pour les modèles provenant de l’API, utilisez une interface sans préfixe “I” mais ajoutez le suffixe “Api” (ex: ProductApi).
Pour les types internes à l’application, utilisez des types (type aliases) clairs et explicites (ex: ProductDetail, CustomerProfile).

Rxjs: $ suffix

Suffixez vos observables Rxjs par un $ pour rendre explicite le fait qu'il s'agit d'un stream de données. 

// GOOD
export class ProductComponent {
    product$: Observable;
}

// BAD
export class ProductComponent {
    productStream: Observable; // Manque le $
}

API: Request & Response

Suffixez les objets envoyés à une API en tant que payload par Request.
Suffixez les objets reçus suite à un appel API par Response.
Typez explicitement les réponses des APIs. 

// Example
export interface CreateOrderRequest {
    userId: number;
    items: OrderItemRequest[];
}

export interface CreateOrderResponse {
    orderId: number;
    status: string;
}

Conventions et bonne pratiques

Documentation Angular best practices
Documentation These ARE the Angular tips you are looking for | John Papa

Template performance

Évitez d'appeler des fonctions ou d’utiliser des pipes impurs dans un template Angular. En effet, lors de la détection des changements, Angular ne peut pas cibler précisément l’élément qui a changé et va réévaluer toutes les fonctions et pipes impurs, pouvant ralentir considérablement l’application.

Pour optimiser, préférez stocker les résultats dans des variables ou propriétés et utilisez des pipes purs si nécessaire.

API: Enums

Privilégiez les enums pour tous les champs réponses d’une API dont la valeur est une série de constantes prédéfinies.
Ceci garantit un nom explicite. 

// Example
export enum OrderStatusApi {
    Pending = "PENDING",
    Shipped = "SHIPPED",
    Delivered = "DELIVERED",
}

APP: Enums

Préférez les literal types (ou types union) pour définir un ensemble de valeurs prédéfinies utilisés dans un composant. Contrairement aux enums,ces types sont plus légers et peuvent parfois être plus simples à manipuler. 

// Using literal types
export type Ordering = "Ascending" | "Descending";

RxJs

Aujourd'hui, il est possible de gérer les événement et les calls asynchrones soit via RxJs, soit via l'api signals d'angular.
Utilisez RxJs uniquement pour les cas complexes et les streams de données où cela apporte une réelle valeur ajoutée.

Si vous utilisez RxJs, respectez les bonnes pratiques suivantes:

Rxjs: inscriptions imbriquées

Évitez les subscribe imbriqués.
Dans cette situation, privilégiez les opérateurs Rxjs (ex: switchMap, mergeMap, etc.).

Documentation : Why You Shouldn’t Nest Subscribes