Auditez l'ensemble du dépôt comme le développeur senior qui vient d'en hériter et qui sera appelé en cas de panne. Ordre d'importance : correct, sûr, tient sous la charge, testé, rapide, allégé. Allégé compte quand même : chaque ligne supplémentaire devra être lue, testée et corrigée plus tard. Il s'agit d'un rapport demandé par l'utilisateur, donc donnez-le en intégralité.
1. Cartographiez d'abord
- Auditez ce que l'utilisateur nomme : un dossier, un package ou l'ensemble du dépôt. Rien de nommé : l'ensemble du dépôt.
- Lisez le README, les configurations de déploiement et de build, la liste des dépendances, les points d'entrée (main, routes, handlers, jobs, commandes CLI) et les tests.
- Trouvez la charge attendue : une personne exécutant un script, ou de nombreux utilisateurs et processus simultanés. Évaluez l'échelle par rapport à cela et dites quelle charge vous avez supposée.
- Retracez les flux principaux de bout en bout : d'où viennent les données, ce qui est stocké, ce qui en sort. Lisez ces chemins complètement : entrées des utilisateurs, transactions financières, authentification, écritures de données, tâches d'arrière-plan, tout ce qui est partagé entre processus.
- Gros dépôt : allez en profondeur là où une erreur coûte le plus cher, pas fichier par fichier. Dites quelles parties vous n'avez pas lues.
2. Recherchez
- Bogue : résultat erroné, plantage, cas limite oublié (vide, zéro, dernier élément, arrondi, fuseaux horaires), appelants qui ne correspondent pas à ce qu'une fonction retourne, la même règle appliquée différemment à deux endroits.
- Risque : failles de sécurité (injection, aléatoire faible, secrets dans le code, contrôles manquants sur les entrées utilisateur), perte de données (erreurs ignorées, écritures dans le mauvais ordre, pas de transaction).
- Échelle : correct pour un utilisateur, erroné pour beaucoup : conditions de compétition (vérification puis écriture), même travail effectué par chaque processus, mémoire ou listes qui ne font que croître, une requête par élément, O(n²) sur grande entrée, état par processus qui doit être partagé.
- Test manquant : logique risquée (une branche, un analyseur, une transaction financière, la sécurité, les écritures de données) sans test qui échoue lorsqu'elle est cassée. Un bon test, pas une couverture.
- Vitesse : les gros ralentissements sont des problèmes. Les petites améliorations (travail répété dans une boucle chaude) sont des suggestions ; certains logiciels comptent chaque milliseconde.
- Allégement : code qui ne devrait pas exister ou qui devrait être plus petit.
- supprimer : code mort, options, indicateurs et configuration inutilisés, fonctionnalités spéculatives
- réutiliser : deux assistants faisant la même chose (gardez-en un, nommez le chemin)
- bibliothèque standard / natif : la bibliothèque standard ou la plateforme le fait déjà ; une dépendance qui fait ce que quelques lignes ou la plateforme peuvent faire
- yagni : interface avec une seule implémentation, fabrique avec un seul produit, wrapper qui ne fait que passer les appels
- fusionner : quasi-copies qui doivent changer ensemble
- scinder : une fonction ou une classe faisant plusieurs tâches sans rapport, ce qui la rend difficile à lire ou à tester. Scinder par tâche, jamais par nombre de lignes, et jamais en assistants qui n'existent que pour raccourcir une fonction.
3. Vérifiez avant de signaler
- Chaque constatation nécessite un cas concret : « cette entrée ou situation conduit à ce résultat erroné ». Pas de cas, pas de constatation.
- Avant de qualifier un code d'inutilisé, greppez tout l'arbre pour le trouver, y compris les tests, les fixtures, la configuration et les références dynamiques ou sous forme de chaîne.
- Un raccourci marqué par un commentaire
shortcut:(ou plus ancienponytail:) qui nomme sa limite est une décision, pas une constatation, sauf si la charge attendue la dépasse déjà. - Proposez la correction la plus petite qui fonctionne. Préférez les corrections qui suppriment du code. N'ajoutez jamais de couches, frameworks ou configuration que le problème ne nécessite pas.
- Pas de goût stylistique, pas de « envisagez », pas de préoccupations vagues.
4. Sortie
Anglais très simple : phrases courtes, mots courants. Expliquez un terme technique la première fois que vous l'utilisez. Le lecteur n'a peut-être jamais vu ce code.
Commencez par What this repo does: en deux ou trois phrases, et la charge
que vous avez supposée.
Ensuite, les constatations en trois groupes, du plus important au moins important, sautez les groupes vides :
- Must fix : bogue, sécurité, perte de données, plantage à la charge attendue.
- Should fix : code risqué sans test, vraie lenteur, duplication, une fonction qui mélange les tâches, code qui ne devrait pas exister.
- Nice to have : petites accélérations, formes plus courtes.
Numérotez les constatations dans tous les groupes, afin que l'utilisateur puisse dire « corrige 2 et 5 ». Au maximum 20 constatations ; si vous en avez laissé de côté des plus petites, dites combien. Chaque constatation a les quatre parties suivantes, chacune d'une ou deux phrases courtes :
- Les commandes atterrissent le mauvais jour (
billing/close_day.py:L40-52)- What this is: À minuit, ce travail ferme la journée et facture toutes les commandes de cette journée.
- Problem: Il prend « aujourd'hui » de l'horloge du serveur, qui tourne en UTC. Une commande passée à 00h30 à Berlin est facturée la veille.
- Fix: Calculez le jour une fois dans le fuseau horaire du magasin :
datetime.now(ZoneInfo("Europe/Berlin")).date(). Une ligne, rien d'autre ne change. - If we skip it: Les commandes tardives affichent la mauvaise date, et la comptabilité les corrige manuellement.
Terminez par :
Verdict:une ligne : sain, ou quoi corriger en premier.Lean: -<N> lines, -<M> dependencies possible.lorsqu'il y a des constatations d'allégement.Not checked:les parties que vous n'avez pas lues ou que vous n'avez pas pu exécuter.
Si rien n'est trouvé : What this repo does:, puis Healthy. Nothing to fix. et
une ligne sur ce que vous avez vérifié.
Rapport unique, ne modifie aucun code.