Documentation des macros dbt en YAML

L’instinct de documenter les macros avec des commentaires dans le fichier SQL est raisonnable mais erroné. La documentation YAML dans _macros.yml est strictement meilleure : elle apparaît dans la documentation dbt, supporte des définitions d’arguments structurées, et crée un emplacement unique pour consulter n’importe quelle macro de votre projet. Les commentaires dans les fichiers SQL sont invisibles pour le système de documentation de dbt et dispersés dans des dizaines de fichiers.

La structure _macros.yml

Un seul fichier _macros.yml à la racine de votre répertoire macros/ couvre tout. Il réside dans macros/_macros.yml et suit le même format version: 2 que les fichiers YAML de modèles :

version: 2

macros:
  - name: cents_to_dollars
    description: |
      Convertit une colonne de centimes entiers en valeur en dollars décimaux.

      ## Usage
      ```sql
      {{ cents_to_dollars('amount_cents') }}
      {{ cents_to_dollars('amount_cents', scale=4) }}
      ```

      ## Notes
      - Suppose que l'entrée est déjà un entier (pas de validation)
      - Utilise ROUND pour des décimales cohérentes
    arguments:
      - name: column_name
        type: string
        description: La colonne contenant les valeurs en centimes
      - name: scale
        type: integer
        description: Nombre de décimales. Par défaut à 2.

Le bloc arguments est ce qui distingue la documentation YAML d’un commentaire : il donne à dbt des métadonnées structurées sur le nom, le type et l’objet de chaque paramètre. Cela apparaît dans la documentation dbt aux côtés de la description, donnant à quiconque atterrit sur votre page de documentation une image complète de l’utilisation de la macro.

Écrire des descriptions qui sont utilisées

Le champ description accepte le Markdown. Utilisez-le.

La chose la plus importante à mettre dans une description est un exemple d’utilisation — spécifiquement, du code copier-coller montrant la macro dans un contexte réel. Les développeurs qui lisent la documentation essaient d’accomplir quelque chose. Ils veulent voir à quoi ressemble l’appel, l’adapter à leur cas, et passer à la suite. Les descriptions abstraites d’arguments n’aident pas autant qu’un exemple concret qu’ils peuvent réellement utiliser.

- name: limit_data_in_dev
  description: |
    Ajoute un filtre de date dans les environnements de développement pour limiter le volume de données.
    Retourne une chaîne vide en production.

    ## Usage
    Ajoutez à la clause WHERE avec AND :
    ```sql
    WHERE 1=1
        {{ limit_data_in_dev('created_at', 7) }}
    ```

    En dev : filtre aux 7 derniers jours.
    En prod : pas de filtre (la clause est une chaîne vide).
  arguments:
    - name: column_name
      type: string
      description: Colonne de date sur laquelle filtrer. Par défaut à 'created_at'.
    - name: days
      type: integer
      description: Nombre de jours à inclure. Par défaut à 3.

Notez ce que fait la description : elle répond immédiatement à la question « comment je l’utilise ? », puis explique la différence de comportement entre les environnements. La section arguments complète les détails sur les valeurs par défaut. Quelqu’un qui lit cela peut copier l’exemple d’utilisation, ajuster le nom de colonne et le nombre de jours, et en finir.

La section notes (si vous en incluez une) est l’endroit pour les pièges : les hypothèses que fait la macro, les cas limites qu’elle ne gère pas, les choses auxquelles faire attention. Soyez honnête. Si la macro suppose une entrée entière et ne valide pas, dites-le. Si elle se comporte de façon inattendue avec des valeurs NULL, documentez-le.

Ce qu’il faut documenter pour chaque macro

Au minimum :

• Une description d’une phrase de ce que fait la macro
• Un exemple d’utilisation montrant l’appel le plus simple
• Tous les arguments avec leurs types et valeurs par défaut

Pour les macros complexes :

• Plusieurs exemples d’utilisation montrant différentes combinaisons d’arguments
• Une section notes pour les pièges et hypothèses
• Des exemples de sortie pour différentes entrées

Pour les macros de surcharge (generate_schema_name, generate_alias_name) :

• Le comportement tenant compte de l’environnement (ce qui se passe en dev vs prod)
• La logique de décision, puisque ces macros sont appelées automatiquement par dbt et le comportement n’est pas toujours évident

L’échec documentaire le plus courant

L’échec le plus courant dans la documentation des macros est d’écrire des descriptions d’arguments qui relient l’évidence :

# Mauvais
arguments:
  - name: column_name
    description: Le nom de colonne.
  - name: scale
    description: L'échelle.

# Meilleur
arguments:
  - name: column_name
    type: string
    description: Colonne contenant des valeurs de centimes entiers (ex. 'amount_cents').
  - name: scale
    type: integer
    description: Nombre de décimales dans la sortie. Par défaut à 2. Utilisez 4 pour les calculs financiers sensibles à la précision.

La meilleure version vous indique quel type de valeur saisir (centimes entiers, pas des dollars), donne un exemple concret et explique quand remplacer la valeur par défaut. La mauvaise version n’est que du bruit.

Documentation et découvrabilité

La documentation YAML s’associe à un bon nommage pour rendre les macros découvrables. Le nom communique l’objectif en un coup d’œil ; la documentation explique comment l’appeler correctement. Un nouveau membre de l’équipe peut parcourir _macros.yml pour comprendre la bibliothèque de macros du projet et utiliser n’importe quelle macro sans demander à un collègue.