code-documentation-pro

Code Documentation Pro

Philosophie : commenter le POURQUOI, pas le QUOI

Le code bien écrit s'auto-documente (noms clairs, fonctions courtes, types expressifs). Un commentaire qui répète le code est du bruit. Un commentaire qui explique une décision non-évidente est de la valeur.

# BAD — répète le code
i += 1  # incrémente i

# GOOD — explique la contrainte métier
i += 1  # l'index commence à 1 côté API fournisseur (spec §4.2), pas 0

Workflow en étapes

1. Choisir le format adapté au langage

2. Structurer chaque docstring publique

Ordre canonique : description courte → paramètres → retour → exceptions → exemple.

Python (Google style) :

def charge_payment(amount: Decimal, currency: str, idempotency_key: str) -> PaymentResult:
    """Débite le montant depuis la passerelle configurée.

    N'effectue aucune opération si la clé d'idempotence est déjà connue (replay safe).

    Args:
        amount: Montant en unité principale (ex: 10.50 pour 10,50 TND).
        currency: Code ISO 4217 en majuscules (ex: "TND").
        idempotency_key: UUID v4 unique par tentative, persisté avant l'appel.

    Returns:
        PaymentResult avec status, transaction_id et timestamp.

    Raises:
        InsufficientFundsError: Si le solde est insuffisant.
        GatewayTimeoutError: Si la passerelle ne répond pas en < 10 s.

    Examples:
        >>> result = charge_payment(Decimal("50.00"), "TND", str(uuid4()))
        >>> assert result.status == "SUCCESS"
    """

TypeScript (JSDoc) :

/**
 * Génère un token JWT signé avec rotation automatique des clés.
 *
 * @param payload - Données à embarquer ; ne pas inclure de PII sensibles.
 * @param ttlSeconds - Durée de validité en secondes (défaut : 3600).
 * @returns Token signé ou lève une erreur si le keystore est indisponible.
 * @throws {KeystoreUnavailableError} Quand aucune clé active n'est trouvée.
 * @example
 * const token = generateJwt({ userId: "u_123", role: "admin" });
 */
export function generateJwt(payload: JwtPayload, ttlSeconds = 3600): string { ... }