#### Table des matières

* [Règles de Formatage](#formattingRules)
  + [Programmation](#programming)
  + [Indentation](#indentation)
  + [Mise en page](#layout)
  + [Longueur de ligne & Taille de fichier](#lineLength)
  + [Commentaires](#comments)
  + [Imports & Organisation](#imports)
* [Conventions de Nommage](#namingConventions)
  + [Noms des Fichiers](#filesNaming)
  + [Noms des Composants](#componentsNaming)
  + [Noms des Services](#servicesNaming)
  + [Noms des Modèles (API / Application)](#modelsNaming)
  + [Rxjs: $ suffix](#rxjsSuffix)
  + [API: Request & Response](#apiRequestAndResponse)
  + [API: Enums](#apiEnums)
* [Conventions et bonnes pratiques](#conventionsAndBestPractices)
* [RxJs](#RxJs)
* [Liens](#links)

[Back to top](#top)

# 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](https://massivepixel.io/blog/angular-best-practices/)

Documentation
[These ARE the Angular tips you are looking for | John Papa](https://www.youtube.com/watch?v=2ZFgcTOcnUg)

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

#### Pipe async

Utilisez l’opérateur `async` (pipe async) dans les templates Angular pour que les observables soient automatiquement gérés par Angular.

Documentation :
[How to use the ASYNC PIPE effectively in Angular Templates](https://www.youtube.com/watch?v=ev1yE0SYs9Y)

#### 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](https://medium.com/ngconf/why-you-shouldnt-nest-subscribes-eafbc3b00af2)

#### Rxjs: Se désinscrire

Gérez la désinscription des observables Rxjs au sein de votre code pour éviter les fuites mémoire.

Documentation :
[6 Ways to Unsubscribe from Observables in Angular](https://blog.bitsrc.io/6-ways-to-unsubscribe-from-observables-in-angular-ab912819a78f)

## Liens

* [Angular Official Style Guide](https://angular.dev/style-guide)
* [Angular Documentation](https://angular.dev/overview)
* [Tailwind CSS Documentation](https://tailwindcss.com/docs)
* [MDN JavaScript](https://developer.mozilla.org/en-US/docs/Web/JavaScript)
* [TypeScript Documentation](https://www.typescriptlang.org/docs/)