Conventions de nommage des macros dbt

Le nom d’une macro est sa documentation au point d’appel. {{ cents_to_dollars('amount_cents') }} explique ce qui se passe sans ouvrir le fichier de macro. {{ process_amount('amount_cents', true, 0.1) }} nécessite de consulter l’implémentation. Les noms de macros sont lus bien plus souvent que n’importe quelle description dans _macros.yml.

Préfixes verbaux pour les actions

Les macros d’action — celles qui récupèrent des données, génèrent du SQL ou transforment une sortie — devraient commencer par un verbe qui signale le type d’action :

get_ pour les macros qui récupèrent des données ou des valeurs :

get_column_values — récupère les valeurs distinctes d’une colonne
get_latest_partition — retourne la date de partition la plus récente

generate_ pour les macros qui créent des structures SQL :

generate_surrogate_key — produit une colonne de clé hashée
generate_schema_name — macro de surcharge de dbt pour le nommage des schémas

format_ pour les macros qui transforment ou présentent des valeurs :

format_timestamp — standardise un timestamp selon un pattern donné
format_currency — ajoute des symboles monétaires et le formatage

Le préfixe verbal vous indique ce qui est attendu avant même d’avoir lu les arguments. get_ signifie que la macro va interroger quelque chose ou faire une recherche. generate_ signifie qu’elle produit du SQL. format_ signifie qu’elle fait de la logique de présentation. Ces distinctions comptent quand vous parcourez un modèle pour comprendre ce qui se passe.

Noms descriptifs pour les transformations

Pour les macros de transformation, choisissez des noms qui décrivent la transformation elle-même plutôt qu’une catégorie générique :

cents_to_dollars plutôt que convert_amount
extract_domain_from_email plutôt que parse_email
calculate_days_since plutôt que date_diff_helper

Le nom devrait répondre à « que fait cela ? » sans avoir à ouvrir le fichier. convert_amount pourrait convertir des dollars en euros, des centimes en dollars, le brut en net, ou une douzaine d’autres choses. cents_to_dollars fait exactement une chose et son nom le dit.

Résistez à la tentation de nommer les choses de façon générique parce que vous pensez que ce sera plus réutilisable. Une macro nommée convert_amount qui fait de la conversion centimes-vers-dollars n’est qu’une macro avec un nom menteur. Si vous avez ultérieurement besoin d’un autre type de conversion de montant, écrivez une nouvelle macro avec un nom spécifique.

Préfixe underscore pour les helpers internes

Quand une macro est un helper appelé par d’autres macros — pas destinée à être utilisée directement dans les modèles — préfixez-la d’un underscore :

{% macro _build_join_condition(columns) %}
    {# Helper interne, pas pour une utilisation directe dans les modèles #}
    {% for col in columns %}
        source.{{ col }} = target.{{ col }}
        {% if not loop.last %} AND {% endif %}
    {% endfor %}
{% endmacro %}

{% macro generate_merge_statement(source, target, columns) %}
    {# Macro publique qui utilise _build_join_condition en interne #}
    MERGE {{ target }} AS target
    USING {{ source }} AS source
    ON {{ _build_join_condition(columns) }}
    ...
{% endmacro %}

L’underscore signale « ne pas appeler directement ». Votre équipe peut utiliser generate_merge_statement sans comprendre les mécanismes internes de construction des conditions de jointure. Elle n’a pas besoin de savoir que _build_join_condition existe.

C’est particulièrement valable dans les grands projets où le répertoire macros/ contient des dizaines de fichiers. Le préfixe underscore rend immédiatement visible l’API publique de votre bibliothèque de macros — c’est chaque fichier qui ne commence pas par underscore.

Une macro par fichier, nom de fichier identique au nom de macro

C’est l’une des conventions les plus pratiques que vous puissiez adopter, et elle vient du guide de style Brooklyn Data.

Quand vous avez besoin de cents_to_dollars, vous savez qu’elle réside dans cents_to_dollars.sql. Pas besoin de fouiller dans un fichier utils.sql. Pas de défilement dans un fichier de 500 lignes avec douze macros sans rapport. Ouvrez simplement le fichier portant le nom de la macro.

Cette convention interagit bien avec le préfixe underscore. Votre dossier macros/utils/ pourrait ressembler à :

utils/
├── cents_to_dollars.sql
├── limit_data_in_dev.sql
├── add_audit_columns.sql
└── _build_where_clause.sql    # helper interne

Le helper interne côtoie les macros publiques mais son préfixe underscore clarifie son statut. Quand un nouvel arrivant parcourt macros/utils/, il voit immédiatement ce qui est public (cents_to_dollars, limit_data_in_dev, add_audit_columns) et ce qui est interne (_build_where_clause).

L’alternative — regrouper plusieurs macros dans un fichier — crée plusieurs problèmes : la recherche floue dans votre éditeur affiche le mauvais nom de fichier, la convention s’effondre quand des macros bougent entre fichiers, et il est tentant d’ajouter des macros à un fichier existant plutôt que de réfléchir soigneusement à l’endroit où elles appartiennent.

Ce qu’il faut éviter

Les noms de helpers génériques. utils, helper, misc ne sont pas des noms. Si une macro va dans utils/, son nom de fichier individuel a encore besoin d’un nom spécifique.

Les noms de transformation sans verbe. timestamp_format, currency_converter, email_parser — ces noms ressemblent à des noms communs. Utilisez format_timestamp, convert_currency, extract_domain_from_email. Les verbes communiquent l’action.

Les abréviations. calc_mrr, gen_sk, fmt_ts — économisez quelques caractères, perdez toute clarté. Le SQL compilé va s’exécuter sur un entrepôt qui se fiche de la longueur des noms de fichiers. Écrivez-le en entier.

Les numéros de version dans les noms. Si vous vous retrouvez à écrire cents_to_dollars_v2, vous avez atteint un scénario de changement cassant qui devrait utiliser le pattern de dépréciation, pas un nom versionné en production.

Le lien avec la documentation

Le nommage et la documentation fonctionnent ensemble. Une macro bien nommée nécessite moins de documentation car le nom communique l’objectif. Une macro mal nommée nécessite de longues descriptions pour compenser. Même les bons noms ne remplacent pas une entrée _macros.yml avec des exemples d’utilisation — voir Documentation des macros dbt en YAML pour des patterns de documentation qui complètent le nommage plutôt que de le répéter.