Documentation code : Comment écrire une doc que les développeurs vont vraiment lire

# README.md (Last updated: 2021)

## Setup
Run `npm install`

(Mais le projet utilise pnpm depuis 2023)

// ❌ Commentaire pour expliquer code obscur
// Check if user can buy (age > 18 and balance > price)
if (u.a > 18 && u.b > p) {
  // Process purchase
  db.insert({ uid: u.id, pid: p.id });
}

// ✅ Code explicite, pas besoin de commentaire
function canUserPurchase(user: User, product: Product): boolean {
  const isAdult = user.age >= MINIMUM_AGE;
  const hasSufficientBalance = user.balance >= product.price;

  return isAdult && hasSufficientBalance;
}

if (canUserPurchase(user, product)) {
  createPurchase(user, product);
}

// ❌ Décrit CE QUE fait le code (évident)
// Incrémente counter
counter++;

// ✅ Explique POURQUOI (pas évident)
// Workaround: API returns duplicates, dedupe client-side
// TODO: Fix in API (ticket #1234)
counter++;

// ✅ Context important
// Using polling instead of WebSocket because:
// 1. Corporate firewalls block WS
// 2. 90% of users won't benefit (rarely updates)
// 3. Simpler implementation (no reconnect logic)
setInterval(checkUpdates, 30000);

// ✅ Warning important
// IMPORTANT: Always call cleanup() after use
// Otherwise: memory leak (event listeners not removed)
class DataFetcher {
  // ...

  cleanup() {
    this.removeAllListeners();
  }
}

// ✅ Algorithme non-trivial
/**
 * Calculate shipping cost using tiered pricing:
 *
 * Weight (kg)  | Price (€/kg)
 * -------------|-------------
 * 0-5          | 2.50
 * 5-20         | 1.80
 * 20+          | 1.20
 *
 * Example: 15kg package
 * - First 5kg: 5 × 2.50 = 12.50
 * - Next 10kg: 10 × 1.80 = 18.00
 * - Total: 30.50€
 */
function calculateShippingCost(weightKg: number): number {
  // Implementation
}

# Project Name

## What is this?
[1-2 sentences describing the project]

## Quick Start
```bash
npm install
npm run dev

npm test

/users/{id}:
  get:
    summary: Get user by ID
    description: |
      Returns user data. Includes profile info and settings.

      **Rate limit:** 100 req/min per API key

      **Permissions:** Requires `users:read` scope
    parameters:
      - name: id
        in: path
        required: true
        schema:
          type: integer
        example: 123
    responses:
      '200':
        description: User found
        content:
          application/json:
            example:
              id: 123
              name: "Alice"
              email: "alice@example.com"
      '404':
        description: User not found

/**
 * Get user by ID
 *
 * @route GET /api/users/:id
 * @param {number} id - User ID
 * @returns {User} User object
 * @throws {404} User not found
 * @example
 * GET /api/users/123
 * → { "id": 123, "name": "Alice" }
 */
router.get('/users/:id', async (req, res) => {
  // Implementation
});

// Tool: TypeDoc, JSDoc → Génère OpenAPI

/**
 * Calculate discount based on user tier and order total.
 *
 * Discount tiers:
 * - Standard: 0%
 * - Premium: 5%
 * - Enterprise: 10%
 *
 * Additional 5% if order > €1000
 *
 * @param user - User object with tier property
 * @param orderTotal - Total order amount in euros
 * @returns Discount amount in euros
 *
 * @example
 * calculateDiscount(premiumUser, 500)
 * // Returns: 25 (5% of 500)
 *
 * @example
 * calculateDiscount(premiumUser, 1200)
 * // Returns: 120 (10% of 1200: 5% tier + 5% volume)
 */
function calculateDiscount(user: User, orderTotal: number): number {
  let discountPercent = 0;

  // Tier discount
  if (user.tier === 'premium') discountPercent += 5;
  if (user.tier === 'enterprise') discountPercent += 10;

  // Volume discount
  if (orderTotal > 1000) discountPercent += 5;

  return orderTotal * (discountPercent / 100);
}

# README (écrit 2021, jamais mis à jour)

Run: `npm start`

// Mais maintenant c'est `npm run dev`

// ✅ Doc = Code (toujours synchro)
const CONFIG = {
  /**
   * Server port. Default: 3000
   * Override with PORT env var
   */
  PORT: parseInt(process.env.PORT || '3000'),

  /**
   * Database URL
   * Format: postgresql://user:pass@host:port/db
   */
  DATABASE_URL: process.env.DATABASE_URL!,
};

// ✅ Tests documentent behavior
describe('calculateDiscount', () => {
  it('gives 5% to premium users', () => {
    const user = { tier: 'premium' };
    expect(calculateDiscount(user, 100)).toBe(5);
  });

  it('gives additional 5% for orders > €1000', () => {
    const user = { tier: 'premium' };
    expect(calculateDiscount(user, 1200)).toBe(120); // 10% total
  });

  it('gives 0% to standard users on small orders', () => {
    const user = { tier: 'standard' };
    expect(calculateDiscount(user, 100)).toBe(0);
  });
});

# .github/workflows/docs.yml
name: Documentation

on: [pull_request]

jobs:
  check-docs:
    runs-on: ubuntu-latest
    steps:
      # Vérifier liens cassés
      - name: Check broken links
        run: markdown-link-check docs/**/*.md

      # Vérifier code examples compilent
      - name: Test code examples
        run: npm run test:docs-examples

      # Générer OpenAPI depuis code
      - name: Generate OpenAPI
        run: npm run generate:openapi

      # Fail si OpenAPI pas à jour
      - name: Check OpenAPI up-to-date
        run: git diff --exit-code docs/api/openapi.yaml

❌ README with 2000 lines

✅ README with:
   - Quick start (50 lines)
   - Links to detailed guides

// ❌ Useless comments
// Get user
const user = getUser();

// Set name
user.name = name;

// Save user
saveUser(user);

// ✅ No comments needed (code clear)
const user = getUser();
user.name = name;
saveUser(user);

❌ README écrit, jamais testé
   → Étapes manquantes, obsolète

✅ README testé à chaque nouveau dev
   → Toujours à jour