Catégorie : Méthodes, Design & Philosophie

Fiable et maintenable — deux mots qu’on entend souvent ensemble, et qu’on oppose rarement à quoi que ce soit de concret. Tout le monde veut un site fiable et maintenable. Personne ne veut un site fragile et incompréhensible. La vraie question n’est pas l’objectif — c’est les décisions qui y mènent. Cet article est ma réponse à cette question : ce que je fais concrètement, dans quel ordre, et pourquoi.

Ce que « fiable et maintenable » signifie en pratique

Fiable ne veut pas dire « sans bugs ». Aucun système non trivial n’est sans bugs. Fiable veut dire que les bugs sont détectés avant la production, que quand ils arrivent en production leur impact est limité, et qu’ils sont corrigés rapidement. Maintenable ne veut pas dire « code parfait ». Ça veut dire que n’importe quel membre de l’équipe peut comprendre, modifier, et déployer n’importe quelle partie du système sans avoir à solliciter le seul qui « sait comment ça marche ».

Ces quatre propriétés ne s’obtiennent pas en ajoutant de la complexité — elles s’obtiennent en la maîtrisant. Un système avec trois couches bien séparées est plus fiable et plus maintenable qu’un système avec dix couches mal définies. La sophistication technique, utilisée sans discernement, produit l’effet inverse de celui recherché.

Décision n°1 — Choisir une stack ennuyeuse

Le premier choix structurant est la stack. Et la meilleure stack pour un site fiable et maintenable est, presque systématiquement, une stack ennuyeuse — pas au sens péjoratif, mais au sens de « éprouvée, documentée, avec une large communauté, des patterns établis, et des développeurs disponibles sur le marché ».

Ce n’est pas un argument contre l’innovation — c’est un argument pour distinguer les expérimentations des projets de production. Tester un nouveau framework sur un side project est une excellente idée. L’adopter pour le système de paiement d’un e-commerce parce qu’il a eu beaucoup d’étoiles GitHub en six mois est une décision qui se paiera en maintenance pendant des années.

Décision n°2 — Typer tout ce qui traverse une frontière

TypeScript strict n’est pas une contrainte — c’est un filet de sécurité qui détecte des bugs à la compilation plutôt qu’en production. La vraie valeur du typage n’est pas dans les fonctions internes d’un module, où le contexte est immédiat — elle est dans ce qui traverse les frontières : les API, les événements, les arguments de fonctions exportées, les données en base.

// tsconfig.json — configuration stricte
{
  "compilerOptions": {
    "strict":               true,    // active tous les checks stricts
    "noUncheckedIndexedAccess": true,    // arr[i] peut être undefined
    "exactOptionalPropertyTypes": true, // distinction undefined / absent
    "noImplicitReturns":    true,    // toutes les branches retournent une valeur
    "noFallthroughCasesInSwitch": true
  }
}

// Typer les frontières — API response
// ✗ Sans type — une propriété manquante casse en production
const data = await fetch('/api/user').then(r => r.json());
data.username.toUpperCase()  → TypeError si username est undefined

// ✓ Avec validation au runtime — zod parse à la frontière
import { z } from 'zod';

const UserSchema = z.object({
  id:       z.string().uuid(),
  username: z.string().min(1),
  email:    z.string().email(),
  role:     z.enum(['admin', 'user', 'readonly']),
});

type User = z.infer<typeof UserSchema>;

const raw  = await fetch('/api/user').then(r => r.json());
const user = UserSchema.parse(raw);
→ si la réponse API est malformée, l'erreur est explicite ici — pas plus loin dans le code

La validation au runtime (zod, valibot, arktype) combinée au typage statique est la réponse aux frontières — elle garantit que les données qui entrent dans le système correspondent exactement au contrat déclaré. Une API qui change son schéma sans prévenir ne passe plus silencieusement — elle produit une erreur explicite, au bon endroit, avec un message lisible.

Décision n°3 — Des tests proportionnels au risque, pas à la couverture

La couverture de code est un indicateur utile — mais un mauvais objectif. Un projet à 95% de couverture peut avoir des tests qui valident uniquement que les fonctions s’exécutent sans lever d’exception. Un projet à 70% de couverture peut avoir des tests qui couvrent tous les cas d’erreur des parcours critiques. Le bon objectif est la couverture des risques métier, pas la couverture des lignes.

// Calibrer les tests par niveau de risque

// Risque haut — logique métier critique
→ tests unitaires exhaustifs : tous les cas nominaux, toutes les erreurs, tous les edge cases
→ ex. : calcul de prix, gestion des permissions, validation des données

describe('calculateOrderTotal', () => {
  it('applique la remise sur le sous-total avant les taxes', () => {
    expect(calculateOrderTotal({ subtotal: 100, discount: 0.2, taxRate: 0.2 })).toBe(96);
  });
  it('rejette une remise supérieure à 100%', () => {
    expect(() => calculateOrderTotal({ subtotal: 100, discount: 1.5, taxRate: 0.2 }))
      .toThrow('Discount cannot exceed 100%');
  });
});

// Risque moyen — contrats d'intégration
→ tests d'intégration sur les endpoints critiques
→ ex. : POST /api/orders retourne 201 avec le bon corps

// Risque haut — parcours utilisateurs critiques
→ tests E2E smoke : connexion, checkout, action principale du produit
→ 10 à 20 tests — suffisant pour détecter les régressions majeures en < 3 min

// Risque bas — composants UI sans logique
→ pas de tests ou snapshot tests — la valeur ne justifie pas le coût de maintenance

Décision n°4 — Séparer les couches pour les changer indépendamment

La maintenabilité repose en grande partie sur une propriété simple : pouvoir changer une chose sans casser une autre. Cette propriété s’obtient en séparant les couches de responsabilité — pas par conformité à un pattern d’architecture, mais parce que les couches évoluent à des rythmes différents.

// Séparation des couches — exemple concret Next.js / Node

// Couche UI — affichage, pas de logique métier
// app/orders/page.tsx
export default async function OrdersPage() {
  const orders = await getOrders();     // appel au service — pas de SQL ici
  return <OrderList orders={orders} />;
}

// Couche service — logique métier, pas de SQL
// services/orders.ts
export async function getOrders(userId: string): Promise<Order[]> {
  const raw = await orderRepository.findByUser(userId);
  return raw.filter(o => o.status !== 'cancelled');  // règle métier ici
}

// Couche accès aux données — SQL, pas de logique métier
// repositories/order.ts
export const orderRepository = {
  async findByUser(userId: string): Promise<OrderRow[]> {
    return db.query(
      'SELECT * FROM orders WHERE user_id = $1 ORDER BY created_at DESC',
      [userId]
    );
  },
};

Cette séparation n’est pas du dogmatisme architectural — c’est une décision pratique. Migrer de PostgreSQL vers une autre base de données n’affecte que la couche repository. Changer la règle métier « masquer les commandes annulées » n’affecte que le service. Revoir le design de la liste des commandes n’affecte que le composant UI. Sans séparation, chaque changement est une opération chirurgicale dans un code entremêlé.

// ✗ Le problème de l'entrelacement — impossible à maintenir
// app/orders/page.tsx — SQL + logique métier + UI dans un seul fichier
export default async function OrdersPage() {
  const rows = await db.query('SELECT * FROM orders WHERE...');
  const filtered = rows.filter(o => o.status !== 'cancelled');
  const total    = filtered.reduce((acc, o) => acc + o.total, 0);
  return <div><p>Total : {total}</p>{filtered.map(...)}</div>;
  → modifier la query SQL oblige à comprendre le composant
  → tester la logique métier oblige à mocker la base de données
  → un nouveau développeur ne sait pas par où commencer
}

Décision n°5 — L’observabilité dès le premier déploiement

Un site fiable est un site dont on sait à tout moment s’il fonctionne correctement — pas parce qu’un utilisateur a signaléun problème, mais parce que les métriques l’ont indiqué avant lui. L’observabilité n’est pas une fonctionnalité à ajouter plus tard — c’est une propriété qu’on construit dès le premier déploiement, parce que rétrofit est dix fois plus coûteux.

// Les trois couches d'observabilité minimales

// 1. Logs structurés — lisibles par les humains et les machines
import pino from 'pino';

const logger = pino({
  level:     process.env.LOG_LEVEL ?? 'info',
  base:      { service: 'api', version: process.env.APP_VERSION },
  timestamp: () => `,"time":"${new Date().toISOString()}"`,
});

// Log avec contexte structuré — interrogeable, filtrable
logger.info({ userId, orderId, amount, duration: 142 }, 'order.created');
→ recherchable par userId, orderId — pas du texte plat non structuré

// 2. Métriques — taux d'erreur, latence, saturation
// voir article "pipeline CI/CD" pour l'instrumentation Prometheus complète

// 3. Alertes — notification proactive, pas réactive
Règle minimale : alerte si taux d'erreur 5xx > 1% sur 5 minutes
Règle minimale : alerte si latence P95 > 2x la baseline sur 10 minutes
Règle minimale : alerte si uptime < 99.9% sur l'heure passée

La différence entre un log structuré et un `console.log` n’est pas esthétique — c’est la différence entre « chercher dans des logs plats pendant deux heures » et « filtrer par orderId et trouver l’erreur en trente secondes ». Le choix se fait au moment d’écrire le premier log — pas au moment de l’incident.

Décision n°6 — Une documentation qui reste à jour

La documentation technique se dégrade inévitablement — sauf si elle est intégrée dans le workflow de développement de façon à ce que la mettre à jour soit la résistance minimale. Une documentation dans un Confluence séparé, mise à jour manuellement, sera périmée dans trois mois. Une documentation dans le dépôt, à côté du code, avec une PR qui la met à jour en même temps que le code, a une chance de survivre.

Nuances — ce que je n’applique pas systématiquement

Le positionnement « voilà ma méthode » est incomplet sans les nuances. Ces décisions ont des coûts — et certains projets ne les justifient pas.

Conclusion

Fiable et maintenable ne sont pas des propriétés qu’on ajoute après coup — ce sont des décisions qu’on prend (ou ne prend pas) à chaque étape de la conception. La stack ennuyeuse, le typage aux frontières, les tests calibrés sur le risque, la séparation des couches, les logs structurés, la documentation qui reste à jour — chacune de ces décisions est indépendante, et chacune contribue. Aucune ne nécessite une refonte complète. Elles s’ajoutent progressivement, et leurs effets sont cumulatifs.

La nuance honnête : aucune de ces décisions ne garantit un système parfait. Elles garantissent un système dont les problèmes sont détectables rapidement, diagnostiquables efficacement, et corrigeables sans chirurgie dans du code entrelacé. C’est la définition pratique de la fiabilité — pas l’absence de bugs, mais la capacité à les gérer sans panique.

Un site fiable et maintenable n’est pas le résultat d’une architecture grandiose — c’est le résultat de décisions raisonnables, prises tôt, appliquées avec constance. La sophistication est tentante. La discipline, plus utile.

Le site de PYKEngine est un fichier HTML, un fichier CSS, quelques SVG. Pas de React, pas de bundler, pas de Node.js en production. Ce n’est pas une contrainte budgétaire ou une limite technique — c’est une décision d’architecture raisonnée, documentée, et défendable. L’industrie du développement web a une tendance structurelle à l’isomorphisme de stack : appliquer la même architecture à tous les problèmes, indépendamment de leur nature, parce que c’est ce qu’on connaît. Un site vitrine statique construit avec un framework full-stack n’est pas plus professionnel qu’un site HTML bien écrit. Il est juste plus complexe — et la complexité accidentelle est un risque, pas une feature.

Ce que « minimaliste » ne signifie pas

Minimaliste ne signifie pas artisanal, ni primitif, ni fait par défaut. C’est une réponse proportionnée à un problème précis. Un site portfolio de consulting — quelques pages statiques, des articles, un formulaire de contact — n’a structurellement pas les mêmes contraintes qu’une application SaaS avec authentification, catalogue dynamique et dashboard temps réel.

L’erreur de raisonnement la plus courante est l’isomorphisme de stack : utiliser partout la même architecture parce que c’est l’architecture qu’on maîtrise, pas parce que c’est l’architecture que le problème appelle. Un développeur React qui construit un site vitrine en React n’optimise pas pour le problème — il optimise pour sa zone de confort. Ce n’est pas un reproche, c’est une observation sur comment les décisions d’architecture se prennent réellement dans les équipes.

L’argument de performance — structurel, pas configuré

Un fichier HTML servi depuis un CDN n’a rien à calculer. Le navigateur reçoit le contenu final, le parse, l’affiche. Il n’y a pas de bundle JavaScript à télécharger avant que la page soit visible, pas de runtime à initialiser, pas d’hydratation à attendre. La performance maximale est le point de départ structurel — pas un objectif à atteindre après optimisation.

Ces chiffres sont indicatifs mais structurellement corrects. Un Next.js optimisé peut approcher 500ms de LCP avec du travail. Un HTML statique y est sans effort. La différence n’est pas la performance peak — c’est le coût pour l’atteindre et le maintenir.

L’argument de sécurité — surface d’attaque et supply chain

La surface d’attaque d’un site statique est structurellement minimale. Il n’y a pas de serveur d’application à compromettre, pas de base de données à requêter, pas de runtime à exploiter, pas de dépendances à empoisonner. Les vecteurs d’attaque se réduisent à la configuration du CDN et aux headers HTTP — configurables une fois, stables dans le temps.

# npm audit sur un projet Next.js standard — 6 mois sans maintenance
found 4 vulnerabilities (1 low, 2 moderate, 1 high)
  run `npm audit fix` to fix them, or `npm audit fix --force`
  (breaking changes possible)

# npm audit sur le site PYKEngine
No known vulnerabilities found
  (0 packages installed)

Ce n’est pas de la chance. C’est la conséquence directe d’avoir zéro dépendance. Les attaques supply chain npm sont documentées et récurrentes : event-stream (2018), ua-parser-js (2021), node-ipc (2022). Chaque paquet dans node_modules est un vecteur potentiel — et un projet Next.js standard en installe 700 à 800. Il n’existe pas de moyen raisonnable d’auditer manuellement cette surface.

Un site statique n’a pas de supply chain logicielle à sécuriser. C’est une propriété structurelle, pas une configuration.

L’argument de maintenance — coût total sur la durée

La durée de vie d’un fichier HTML est celle du web. Un fichier HTML écrit en 2010 fonctionne dans tous les navigateurs en 2026 sans modification. Un projet create-react-app de 2018 est officiellement déprécié. Un projet Next.js 12 nécessite une migration pour passer à Next.js 15. Un projet Webpack 4 est en fin de vie.

# Dépendances directes d'un projet Next.js standard
next, react, react-dom, typescript, @types/react, @types/node,
eslint, eslint-config-next, tailwindcss, postcss, autoprefixer
→ ~720 packages installés, ~280 Mo dans node_modules
→ breaking changes majeurs tous les 12–18 mois
→ migrations : Next.js 12→13→14→15 = ~3 jours de travail chacune

# Dépendances du site PYKEngine
→ 0 package
→ 0 node_modules
→ 0 build step
→ 0 pipeline CI/CD de compilation
→ 0 migration prévue

Le coût total de possession d’une stack framework inclut des postes souvent sous-estimés en amont : les migrations majeures, la gestion des breaking changes dans les dépendances transitives, les alertes de sécurité à traiter, les pipelines de build à maintenir, la documentation à mettre à jour à chaque montée de version, la montée en compétence de chaque nouveau développeur sur les spécificités du setup.

Pour un site statique de quelques pages, ce coût n’a aucune contrepartie en valeur fonctionnelle. C’est de la complexité sans retour.

Le signal — ce que le choix de stack communique

Il y a un argument méta que les arguments techniques ne couvrent pas entièrement : ce que le choix de stack révèle sur le raisonnement de celui qui le fait.

Un consultant technique dont le site vitrine est sur-ingénié envoie un signal ambigu. Si vous choisissez un framework full-stack avec SSR, hydratation, système de composants et pipeline de build pour afficher votre nom, trois pages de services et un formulaire de contact, vous signalez que vous optimisez pour la sophistication apparente plutôt que pour la valeur délivrée. C’est exactement le type de décision qu’un client paye un consultant senior pour éviter dans ses propres équipes.

L’expertise d’un ingénieur senior ne se mesure pas à la liste des technologies qu’il est capable d’utiliser. Elle se mesure à sa capacité à choisir la solution adaptée à chaque contexte — y compris, et surtout, quand cette solution est la plus simple disponible. Choisir HTML pour un site statique n’est pas un aveu de limitation. C’est une démonstration de discernement.

Nuances — ce que cette approche ne dit pas

Un argument aussi tranchant mérite d’être tempéré. Quelques nuances que l’enthousiasme pour la simplicité peut faire oublier.

Quand le HTML statique ne tient plus

L’honnêteté intellectuelle exige de nommer les limites explicitement. Le HTML statique cesse d’être la bonne réponse quand :

Contrainte	Seuil de bascule	Alternative adaptée
Contenu dynamique	Données personnalisées par utilisateur, authentification, temps réel	Next.js / Remix / SvelteKit selon la complexité
Volume éditorial	Contenu mis à jour fréquemment par des non-développeurs	Astro + CMS headless (Sanity, Contentful), ou Hugo
Richesse d’interface	Interactions complexes, état global, formulaires dynamiques multi-étapes	React, Vue, Svelte selon le contexte et l’équipe
Taille d’équipe front	Plusieurs développeurs front en parallèle sur un même codebase	Système de composants avec un framework — la convention prime
Volume de pages	Dizaines ou centaines de pages avec structure partagée	Générateur statique (Astro, Hugo, Eleventy) — statique conservé
Internationalisation	Contenu multilingue avec routing par locale	Next.js i18n ou framework avec i18n natif

Aucune de ces contraintes ne s’applique actuellement au site de PYKEngine. Ce qui valide le choix — mais uniquement dans ce contexte.

Conclusion

Le site de PYKEngine est du HTML statique parce que c’est la réponse correcte au problème posé. Pas parce que les frameworks sont mauvais — ils résolvent des problèmes réels et complexes. Mais parce que la compétence clé d’un ingénieur senior est de distinguer les problèmes qui nécessitent des solutions complexes de ceux qui n’en ont pas besoin. Performance maximale par défaut. Surface d’attaque nulle. Coût de maintenance zéro. Durée de vie indéfinie.

Le choix le plus simple est souvent le choix le plus difficile à assumer — et le plus révélateur de la maturité technique de celui qui le fait.