Construire un modèle

Un modèle peut agréger des données, projeter plusieurs scénarios ou calculer des ratios. Quelle que soit son ampleur, le code gagne à appliquer des conventions constantes. Une équipe peut alors se concentrer sur les règles financières plutôt que sur la forme de chaque fonction.

Les formateurs et vérificateurs repèrent une partie des problèmes de présentation. Ils ne choisissent pas à votre place les noms, les limites entre modules, la définition d’un indicateur ou le niveau de détail de sa documentation.

Pourquoi partager un style de code ?

Python dispose de conventions documentées dans PEP 8. Les suivre facilite la lecture dans des projets différents et permet aux outils de contrôle de faire leur travail. Une équipe peut adopter des adaptations, mais elle devrait les écrire et les appliquer de manière uniforme.

Style par défaut (PEP 8)

Quelques choix de mise en forme rendent les fonctions faciles à parcourir :

• utilisez quatre espaces pour l’indentation et conservez l’encodage UTF-8 ;
• séparez les fonctions et les classes par des lignes blanches ;
• placez chaque import clairement, en séparant bibliothèque standard, bibliothèques externes et modules du projet ;
• préférez les imports explicites à l’import global de tout un module ;
• coupez les expressions longues à un endroit qui rend le calcul lisible ;
• réservez les noms spéciaux comme __version__ aux usages prévus par Python.

La limite de longueur de ligne varie selon les équipes et les outils. Choisissez une valeur raisonnable et configurez le formateur pour éviter les débats de mise en page à chaque modification.

Un formateur comme Black ajuste l’indentation et les retours à la ligne. Un outil d’analyse statique comme Ruff repère des erreurs de style et des constructions douteuses. Ces outils accélèrent la revue, mais un fichier bien formaté peut toujours appliquer une formule financière incorrecte.

Conventions de nommage

Python distingue les classes, les fonctions, les variables et les constantes par leur forme habituelle : classes en CapWords, fonctions et variables en snake_case, constantes en majuscules avec des tirets bas. Une seule convention de langue pour les identifiants évite de mélanger des noms français et anglais dans un même module.

Dans un projet à diffusion internationale, les identifiants anglais sont souvent utiles ; dans un outil interne francophone, des noms français précis peuvent être plus faciles à maintenir. Choisissez une convention et évitez les abréviations opaques.

class ModeleFinancier:
    """Regroupe les calculs d’une analyse de rentabilité."""

TAUX_IMPOSITION = 0.25

def calculer_marge_brute(chiffre_affaires, cout_des_ventes):
    if chiffre_affaires == 0:
        raise ValueError("Le chiffre d’affaires ne peut pas être nul.")
    return (chiffre_affaires - cout_des_ventes) / chiffre_affairesCopier

Un nom comme cout_des_ventes dit davantage que c. Le préfixe _ peut signaler un élément interne à un module ou à une classe, mais ne constitue pas un mécanisme de sécurité.

Appliquer les annotations de type

Les annotations indiquent les types attendus pour les paramètres et les résultats. Elles aident les lecteurs, les éditeurs et certains vérificateurs statiques à repérer une incohérence avant l’exécution.

import pandas as pd

def calculer_marge_brute(
    chiffre_affaires: pd.Series,
    cout_des_ventes: pd.Series,
) -> pd.Series:
    if (chiffre_affaires == 0).any():
        raise ValueError("Le chiffre d’affaires ne peut pas être nul.")
    return (chiffre_affaires - cout_des_ventes) / chiffre_affairesCopier

On peut aussi annoter une valeur qui accepte plusieurs types, une structure de dictionnaire ou une constante. Une annotation ne valide pas automatiquement les données reçues : les entrées issues d’un fichier doivent toujours être contrôlées.

Rédiger des docstrings

Une docstring répond aux questions qu’un collègue se poserait avant d’utiliser la fonction : à quoi sert-elle, quels paramètres faut-il fournir, que renvoie-t-elle et quelles erreurs peut-elle signaler ? Pour un calcul financier, ajoutez la formule, les unités, les conventions de signe et les cas limites.

def calculer_taux_croissance(valeur_actuelle: float, valeur_precedente: float) -> float:
    """Calcule la variation relative entre deux périodes.

    Formule : valeur actuelle / valeur précédente - 1.
    Les deux montants doivent employer la même unité et la même convention de signe.

    Args:
        valeur_actuelle: Montant de la période observée.
        valeur_precedente: Montant de la période de comparaison, différent de zéro.

    Returns:
        Variation sous forme de fraction ; 0.10 représente 10 %.

    Raises:
        ValueError: Si le montant de comparaison est nul.
    """
    if valeur_precedente == 0:
        raise ValueError("Le montant de comparaison ne peut pas être nul.")
    return valeur_actuelle / valeur_precedente - 1Copier

Le format Google est courant, mais les formats NumPy et reStructuredText sont également utilisés. Le format précis importe moins que la présence des informations attendues et l’uniformité du projet.

Créer la documentation

Les docstrings expliquent les fonctions ; la documentation du projet explique comment les combiner et quelles hypothèses générales s’appliquent. Un README peut suffire à un outil interne. Une bibliothèque partagée bénéficiera de tutoriels, d’exemples et d’une référence des fonctions.

Les outils Sphinx et MkDocs peuvent transformer des pages de documentation en site consultable. Les exemples reproductibles peuvent vivre dans un dossier examples/ ou dans des carnets Jupyter dédiés. Une documentation d’entreprise peut aussi expliquer les sources de données autorisées, les définitions retenues et les décisions d’architecture.

Évitez de répéter partout les mêmes détails : la docstring décrit la fonction, le tutoriel montre un parcours d’usage, et le document d’architecture présente les principales responsabilités du modèle.

Revoir le code écrit par une IA

Une réponse qui s’exécute n’est pas encore une modification validée. Relisez les changements comme vous le feriez pour ceux d’un collègue : commencez par comprendre l’intention, puis examinez les conséquences sur les calculs et les autres modules.

Pour un modèle financier, la revue devrait couvrir au minimum :

1. La définition : la formule correspond-elle à la définition retenue par le projet ?
2. Les unités et les signes : les montants et pourcentages sont-ils sur la même base ?
3. Les périodes : les valeurs comparées couvrent-elles les mêmes dates et fréquences ?
4. Les données absentes : leur traitement est-il explicite et cohérent ?
5. La place du code : les calculs, la préparation des données et l’affichage restent-ils dans leurs couches respectives ?
6. La vérification : les tests comportent-ils une valeur attendue contrôlée indépendamment ?

Un exemple bref : l’assistant ajoute un ratio et son test passe. Avant d’accepter, vérifiez que le numérateur et le dénominateur proviennent de la bonne période, qu’ils suivent la convention de signe du projet et que la valeur attendue ne vient pas simplement de la fonction testée.

Demandez à l’assistant de résumer les changements en indiquant les fichiers touchés, la formule appliquée, les hypothèses retenues et les commandes exécutées. Cette synthèse guide la revue, mais ne la remplace pas.

Étape suivante

Les conventions rendent le code lisible ; des tests déterminent si les résultats restent conformes aux règles attendues. Le prochain chapitre explique comment tester son modèle.