# Annexe A1 — Qualité du code

## Charte de nommage

| Élément | Convention | Exemple réel dans le code |
|---|---|---|
| Fonctions, variables | `snake_case` | `create_annonce`, `fichier_id` |
| Classes / exceptions | `PascalCase` | `AnnonceNotFoundError`, `FileValidationError` |
| Constantes | `UPPER_SNAKE_CASE` | `TITRE_MAX_LEN`, `ALLOWED_EXTENSIONS` |
| Modules | `snake_case` court, un rôle par fichier | `annonce_service.py`, `audit_model.py` |

## Séparation stricte des responsabilités

Architecture en couches routes/ → services/ → models/ (voir Bloc 1 — C3/C4).
Aucune route n'exécute de SQL ; aucun modèle ne connaît la logique HTTP.

## Preuve réelle — exécution de flake8 (2026-08-20)

Commande exécutée : `flake8 --max-line-length=110 --exclude=tests app.py
config.py db.py models routes services init_db.py`

```
(sortie vide — 0 violation)
```

**0 violation PEP8/pyflakes** sur l'ensemble de la couche applicative
(app.py, config.py, db.py, models/, routes/, services/, init_db.py — hors
tests). Rapport complet : `docs/evidence/flake8_output.txt`.

## Preuve réelle — exécution de radon (complexité et documentation)

Commande : `radon cc models services routes app.py db.py -s -a`

```
84 blocs (classes, fonctions, méthodes) analysés.
Complexité moyenne : A (1.70)
```

Une complexité cyclomatique moyenne de 1,70 (grade A) signifie que la
quasi-totalité des fonctions n'a qu'un ou deux chemins d'exécution — cohérent
avec la décomposition en étapes indépendantes (ex. upload de fichiers en
8 fonctions, cf. Bloc 3 — C2).

Commande : `radon raw models services routes app.py db.py -s`

```
Total :
    LOC (lignes de code) : 984
    Commentaires : 28 lignes ; commentaires + docstrings : 13 % du total (C+M % L)
```

**Taux de documentation interne mesuré : 13 %**, dans la fourchette cible
8–15 % annoncée dans la Partie 2 (Bloc 1 — C2). Rapport complet :
`docs/evidence/radon_cc_output.txt` et `docs/evidence/radon_raw_output.txt`.

## Taux de réutilisation

Les fonctions de validation et d'autorisation sont centralisées dans
`services/auth_service.py` (décorateurs `require_login`/`require_admin`) et
réutilisées par les 4 blueprints de routes (`annonces`, `fichiers`,
`evenements`, `dashboard`). Les 5 modules de `models/` exposent tous la même
interface (`insert`/`fetch_all`/`get`/`delete`), ce qui a permis d'écrire
`services/` sans dupliquer la logique d'accès aux données.

## Preuve réelle — suite de tests (Bloc 1 — C5, Bloc 3 — C7)

Commande : `pytest tests/ -v` exécutée contre une véritable base MariaDB
10.11 (et non des mocks) :

```
34 passed in 0.5s
```

Répartition : 22 tests unitaires (UT-01 à UT-12, avec variantes), 11 tests
d'intégration (IT-01 à IT-10, avec variante), 6 tests de sécurité (TS-01 à
TS-06). Détail complet dans `docs/evidence/pytest_output.txt` et dans la
Partie 4 (Plan de tests) du présent dossier.

Au cours de l'écriture de cette suite, **3 bugs réels ont été détectés puis
corrigés** grâce aux tests (et non anticipés à l'écriture du code) :
un paramètre par défaut Python évalué à l'import (`Config.UPLOAD_DIR`)
qui ignorait les redirections de répertoire en test, un blueprint Flask
redécoré à chaque création d'application de test, et une confusion entre
"argument non fourni" et "argument explicitement `None`" dans
`is_admin()`. Ce sont des exemples concrets de recherche systématique
d'erreurs (Bloc 1 — C5) et de débogage (Bloc 3 — C5).