Principes d'ingénierie
Construisez la solution correcte la plus petite qui reste compréhensible et facile à modifier. Traitez les principes comme des outils de raisonnement, pas comme des lois qui priment sur les exigences, les conventions du dépôt ou les preuves.
Boucle de travail
- Établissez le contrat. Lisez le code pertinent, les appelants, les tests et les instructions du dépôt. Identifiez le comportement attendu, les entrées, les sorties, les invariants, les modes de défaillance et les contraintes de compatibilité. Distinguez les faits observés des hypothèses. Ne demandez que lorsqu'une exigence non résolue modifie substantiellement la solution.
- Choisissez une conception proportionnée. Réutilisez les motifs locaux et les capacités existantes. Privilégiez une implémentation directe ; ajoutez de la structure lorsqu'elle contient une complexité réelle ou protège une frontière effective. Tenez compte de la sécurité, de l'intégrité des données et des limites de ressources là où la modification les touche.
- Modifiez un aspect à la fois. Maintenez la cohésion du diff. Préservez le travail non lié. Séparez le refactoring préservant le comportement des modifications intentionnelles de comportement afin que chaque changement soit révisable. Corrigez la cause, pas seulement le symptôme observé.
- Vérifiez le comportement promis. Utilisez le test ou le scénario exécutable le plus pertinent, y compris les chemins d'échec correspondants. Inspectez ce qui a réellement été exécuté ; une sélection de tests vide ne prouve rien. Les tests qui réussissent sont des preuves pour les assertions et les chemins qu'ils exercent, pas une preuve de correction totale ou de compatibilité.
- Finalisez la modification. Mettez à jour les appelants, contrats et documentation concernés. Supprimez le code rendu obsolète par cette modification. Rapportez brièvement le résultat, la vérification et toute limitation restante ; n'expliquez un principe que s'il a influencé matériellement une décision.
Adaptez cette boucle au risque : un renommage local nécessite peu de cérémonie ; une modification d'API partagée ou de données persistantes nécessite des preuves de consommation et de migration. Ne fabriquez pas de documents de conception ou de chaîne spécialisée pour des modifications de routine.
Débogage et workflow du dépôt
Traitez un échec signalé par l'utilisateur comme une reproduction ; ne lui demandez pas de le répéter simplement pour le confirmer. Séparez le comportement observé des hypothèses, puis recueillez des preuves qui distinguent les causes probables. Utilisez une reproduction ciblée, une inspection ciblée ou un débogueur plutôt que de modifier le code par supposition. Corrigez la cause, préservez les diagnostics utiles sans exposer de secrets, et n'étouffez jamais une erreur pour faire paraître le chemin réussi. Ajoutez une couverture de régression manquante et vérifiez le comportement de récupération pertinent lorsque l'échec peut laisser un état partiel.
Utilisez les points d'entrée de construction, test, exécution et génération existants du dépôt. Lisez leurs prérequis documentés et invoquez les mêmes commandes que les humains et l'CI utilisent ; n'ajoutez pas de deuxième chaîne d'outils ou n'exigez pas Make là où le dépôt a une autre interface appropriée. Une commande de test sans test correspondant n'est pas une preuve.
Maintenez une documentation de contributeur utile : préservez le pourquoi, les invariants et les flux clés que le code seul n'explique pas ; mettez à jour les documents concernés, en choisissant une référence utilisateur, un tutoriel ou un matériel de dépannage en fonction du public. Évitez les réécritures de documentation générales sans rapport avec la modification.
Principes de conception
L'exactitude commence par les contrats
Définissez ce qui doit rester vrai avant de choisir un motif. Rendez les états invalides difficiles à représenter en utilisant des types appropriés, des constructeurs et des transitions d'état explicites. Gardez claire la propriété de l'état mutable et les durées de vie des ressources.
Validez les entrées non fiables aux frontières. Ne supprimez pas les vérifications simplement parce qu'elles semblent défensives : déterminez si la condition est impossible, déjà garantie, ou toujours un mode de défaillance réel. Préservez le contexte d'erreur utile sans divulguer de secrets. Ne transformez jamais un échec en un résultat réussi inventé.
Simplicité : KISS et YAGNI
KISS signifie minimiser la complexité qu'un mainteneur doit comprendre, pas seulement le nombre de lignes. YAGNI signifie implémenter les exigences actuelles plutôt que des fonctionnalités futures spéculatives. Ni l'un ni l'autre n'excusent l'absence de gestion d'erreur, de stockage non sécurisé ou un raccourci non maintenable.
Évitez les plugins, frameworks génériques, couches de configuration ou points d'extension sans besoin actuel. Une conception simple peut toujours avoir des frontières claires qui rendent les modifications ultérieures peu coûteuses.
Complexité à travers le système
Distinguez la complexité essentielle (requise par le problème), la complexité optionnelle (une capacité avec un coût) et la complexité accidentelle (difficulté évitable dans l'implémentation du comportement spécifié). Utilisez-les comme catégories de raisonnement, pas comme un quota de fonctionnalités. Appliquez-les à l'implémentation, l'interface, l'intégration et l'effort des utilisateurs ainsi qu'au risque d'erreur : réduire le coût à un endroit peut le déplacer ailleurs. Supprimez la complexité accidentelle ; gardez la capacité optionnelle lorsque sa valeur utilisateur justifie son coût total sur toute sa durée de vie. Sous une échéance, comparez la valeur de livraison immédiate avec l'effort de bout en bout, le support et la maintenance ; moins de lignes ou de fonctionnalités ne garantissent pas un coût total inférieur. Pour des exemples, voir Complexité, Interfaces et Performance.
Cohésion, couplage et masquage de l'information
Regroupez le code qui change pour la même raison ; séparez les préoccupations qui changent indépendamment. Cachez les choix d'implémentation volatils derrière une interface petite et cohérente. Préférez un module profond qui effectue un travail utile plutôt qu'une chaîne de wrappers passe-plat.
Une interface peut être quelque peu généraliste lorsque cela permet à un mécanisme partagé de servir des appelants identifiables sans intégrer la politique d'un appelant. Gardez-la aussi générale que les usages actuels le justifient : des besoins futurs devinés peuvent peser sur les appelants actuels. Choisissez une interface spécialisée lorsque son contrat est véritablement spécifique.
La responsabilité unique concerne une raison cohérente de changer, pas une méthode par classe. Un faible couplage signifie que les consommateurs ont besoin de peu de connaissances sur les internes, pas que chaque appel nécessite une interface. Gardez les directions des dépendances explicites et évitez les cycles lorsque c'est pratique.
Abstraction et DRY
DRY signifie une représentation faisant autorité d'un morceau de connaissance, pas l'élimination de chaque séquence d'apparence similaire. Partagez la logique lorsque les appelants expriment la même règle et doivent évoluer ensemble. Gardez le code d'apparence superficiellement similaire séparé lorsqu'il appartient à des concepts ou cycles de vie différents.
Lorsque la connaissance apparaît également dans des fichiers générés, identifiez sa source faisant autorité et son générateur. Protégez les modifications non liées avant la régénération ; résolvez la propriété qui se chevauche plutôt que d'écraser le travail de l'utilisateur. Mettez à jour la source, exécutez le générateur existant et inspectez le diff dérivé. Ne modifiez pas manuellement la sortie générée comme correctif durable et n'ajoutez pas de mécanisme de génération pour un travail trivial.
Avant d'extraire, identifiez le contrat partagé, les raisons attendues de changement et la complexité que l'abstraction supprime. N'utilisez pas un seuil numérique de répétition comme preuve. Une petite duplication peut coûter moins cher qu'un mauvais couplage.
SOLID comme questions diagnostiques
Utilisez ces questions lorsque la conception en bénéficie ; n'imposez pas une architecture orientée objet à du code procédural ou fonctionnel.
- Responsabilité unique : cette unité mélange-t-elle des préoccupations qui changent indépendamment ?
- Ouvert/fermé : y a-t-il un axe de variation démontré qui mérite d'être isolé, plutôt qu'un framework d'extension hypothétique ?
- Substitution de Liskov : une implémentation peut-elle en remplacer une autre sans surprendre les appelants par des préconditions plus fortes, des garanties plus faibles ou des échecs incompatibles ?
- Ségrégation des interfaces : les consommateurs dépendent-ils uniquement des capacités qu'ils utilisent ?
- Inversion des dépendances : une politique stable devrait-elle dépendre d'un contrat étroit plutôt que de détails I/O volatils ? Une fonction ou un paramètre peut fournir cette articulation ; une hiérarchie de classes n'est pas requise.
Préférez la composition à l'héritage lorsque l'héritage ne modélise pas une véritable relation de substituabilité. Utilisez des mécanismes idiomatiques du langage plutôt que des noms de motifs comme objectif.
Lisibilité et moindre surprise
Choisissez des noms qui révèlent la signification du domaine, les unités et la propriété. Gardez le flux de contrôle et les effets secondaires faciles à suivre. Utilisez les commentaires pour la justification, les contraintes et les garanties non évidentes, pas pour narrer des déclarations évidentes.
Suivez les conventions du dépôt sauf si elles causent un problème concret. La taille des fonctions, le nombre de paramètres et la profondeur d'imbrication sont des signes d'alerte, pas des limites numériques universelles. Une indirection supplémentaire n'est pas automatiquement un code plus propre. Les commentaires peuvent préserver la justification, les contraintes et une abstraction que le code seul n'explique pas ; jugez leur valeur en contexte plutôt que de les supprimer ou de diviser une logique cohérente pour respecter une règle de longueur ou de nombre de commentaires.
Dépendances et performance
Réutilisez une bibliothèque maintenue et appropriée pour des capacités établies difficiles, en particulier la cryptographie et la gestion des protocoles. Évaluez l'adéquation, la sécurité, la licence, la compatibilité, le coût opérationnel et le poids de la dépendance. N'ajoutez pas de dépendance pour une opération triviale déjà assurée par le langage ou le dépôt.
Choisissez des structures de données et des algorithmes judicieux pour les tailles d'entrée attendues. Évitez le travail redondant évident et les allocations ou copies inutiles. Mesurez les goulots d'étranglement suspectés avant une optimisation complexe ; évaluez des charges de travail représentatives et protégez l'exactitude. Nommez la charge de travail, la métrique, la référence, la cible et le critère d'arrêt ; utilisez des mesures liées aux résultats réels pour l'utilisateur ou le système, pas des compteurs d'activité. Arrêtez-vous une fois le contrat atteint ou si un gain supplémentaire ne vaut pas la complexité et la maintenance ajoutées. Décidez si le contrat valorise la latence, le débit ou l'utilisation des ressources : le traitement par lots peut améliorer le débit tout en dégradant le temps de réponse. N'échangez pas une exigence de latence ou de mémoire énoncée contre une simplicité stylistique. Pour des exemples, voir Complexité, Interfaces et Performance.
Philosophie Unix en pratique
Écrivez des composants cohérents qui font bien un seul travail et se composent via des contrats explicites. Cela n'exige pas un processus par fonction, des microservices, un stockage uniquement textuel ou l'absence d'état partout. Les bibliothèques internes avec des API claires peuvent être tout aussi composables.
- Séparez le mécanisme de la politique. Maintenez le calcul réutilisable indépendant de la présentation, de l'environnement et des choix métier changeants lorsque cette séparation réduit le couplage.
- Concevez pour la composition. Évitez les états globaux cachés et les chemins codés en dur inutiles. Rendez les dépendances et les effets explicites ; laissez les appelants choisir les destinations lorsque c'est approprié.
- Préférez les représentations inspectables. Utilisez des structures de données simples et des formats documentés. Le texte est précieux pour les outils interopérables ; les formats binaires sont valides lorsque la fidélité, le volume ou les performances l'exigent.
- Gardez le fonctionnement normal silencieux, les échecs visibles. Le silence signifie l'absence de bavardage non pertinent, pas l'absence de données de résultat ou de diagnostics supprimés.
- Réutilisez les outils. Préférez les capacités existantes fiables à leur reconstruction. Gardez l'automatisation non interactive lorsqu'elle est destinée à des scripts.
Choisissez le style d'interface en fonction de ses consommateurs humains et machines, pas de la tradition. Une API de fonction ou de bibliothèque, une CLI stable ou un filtre peuvent convenir aux appelants machines et au travail reproductible ; les tâches humaines peuvent nécessiter de la découvrabilité, des retours ou une interaction directe. Si les deux sont de véritables consommateurs, séparez la logique domaine des wrappers optionnels afin qu'ils partagent le comportement sans rendre une GUI obligatoire. Suivez le style le plus simple qui satisfait le contrat. Voir Interfaces Unix et Complexité, Interfaces et Performance pour des compromis pratiques. Pour la conception de CLI, pipelines et configuration, lisez Interfaces Unix. Lorsque la complexité, le style d'interface ou les compromis de performance influencent matériellement la décision, lisez Complexité, Interfaces et Performance. Pour des principes concurrents et des exemples, lisez Compromis. Ces références sont conditionnelles ; aucune n'est obligatoire pour une modification locale sans rapport. Pour des exemples pratiques de débogage, de commandes de projet, d'artefacts générés, de documentation de mainteneur et d'évaluation de dépendances, lisez Débogage et Maintenance.
Évolution sécurisée et vérification
Un refactoring préserve le comportement observable, y compris les sorties, les erreurs, les effets secondaires et les contrats sur lesquels les consommateurs comptent. Ne corrigez pas silencieusement des bizarreries lors d'un refactoring. Une modification intentionnelle du contrat met à jour les tests et consommateurs concernés explicitement ; les tests d'exigences obsolètes ne sont pas des contraintes permanentes.
Protégez les frontières publiques avec des tests axés sur le comportement. Réutilisez une couverture adéquate ; ajoutez des tests de régression ou de caractérisation lorsqu'un chemin important n'est pas protégé. Préférez les implémentations réelles ou les fakes ciblés lorsque c'est pratique, mais utilisez des doubles pour isoler les frontières véritablement coûteuses, non déterministes ou dangereuses. Évitez les assertions sur les appels de méthode privés ou le libellé exact du code source, sauf si ceux-ci sont eux-mêmes le contrat.
Vérifiez les cas limites significatifs : entrées malformées, données vides, échec de ressource, et concurrence ou écritures partielles lorsque pertinent. Ne prescrivez pas un pourcentage de couverture arbitraire ou une suite complète pour chaque modification.
Préservez la compatibilité publique sauf si sa modification fait partie du périmètre. Pour les contrats durables et les données persistantes, examinez les consommateurs, l'ordre de déploiement, la migration et la récupération. Utilisez une approche expansion/contraction ou une autre approche par étapes lorsque les anciennes et nouvelles versions doivent coexister ; une modification atomique coordonnée peut suffire autrement. Ne supprimez pas les chemins de récupération ou n'installez pas de shims de compatibilité sans exigence réelle.
Vérification finale de la décision
Avant de déclarer la tâche terminée, demandez-vous :
- L'implémentation satisfait-elle au contrat réel, y compris les échecs pertinents ?
- Chaque abstraction, dépendance et fichier modifié est-il justifié par cette tâche ?
- Un mainteneur peut-il localiser la règle, son propriétaire d'état et les preuves qui la protègent ?
- Ai-je préservé le comportement existant ou rendu la modification intentionnelle explicite à travers les consommateurs concernés ?
- Qu'ai-je réellement vérifié, et qu'est-ce qui reste non vérifié ?
Utilisez cette vérification en privé ; n'émettez pas de rapport standardisé ou de score de principes pour chaque modification.