Règles de rédaction des en-têtes de code

Chaque fichier de code porte un en-tête court qui explique son rôle. Il aide les humains comme les agents IA à se repérer sans lire tout le fichier.

Règles

1re ligne : description concise du rôle du fichier.
Décrire le rôle, pas l’implémentation ligne à ligne ; expliquer le pourquoi.
Viser l’usage : utiliser, maintenir, configurer, déboguer.
Signaler toute contrainte : fichier généré, à ne pas éditer, dépendances.
Anglais, concis ; jamais redire ce que le code exprime déjà.

Admonitions dans l’en-tête (Nix)

L’en-tête d’un module Nix peut contenir des admonitions Starlight (note, tip, caution, danger) : elles alimentent la référence des modules générée par just codegen.

# Module de service : reverse-proxy Caddy pour les services de zone.
#
# :::tip[Activation]
# Activé d'office par les profils d'hôtes exposant des services.
# :::
{ config, lib, ... }:

Fichier généré

Un fichier produit par un outil le dit en en-tête, pour qu’on ne l’édite pas :

# This file is generated by 'just generate' or 'just clean'
# from the configuration file etc/config.yaml
# --> DO NOT EDIT <--