Ce document a été adapté de Avec Jack Bradshaw . Les directives de style Monopole La documentation efficace est la pierre angulaire du développement durable ; cependant, l’inévitabilité de la croissance de l’équipe rend difficile l’écriture de la documentation en tant qu’équipe qui n’est pas fragmentée et incohérente ; par conséquent, un certain degré de coordination entre les contributeurs est nécessaire. Même les ingénieurs solo, qui avaient autrefois un passe libre, doivent maintenant lutter contre l’incohérence de la documentation générée par l’IA. J’utilise moi-même l’IA pour générer une partie de la documentation dans mon dépôt, mais au fil du temps, ils sont devenus insatisfaits des résultats ; en particulier, le manque de cohérence et de cohérence dans toute la base de code. Ma première tentative de résoudre ce problème a abouti à la création d'un Document Standard de Documentation Générale contenant 13 règles prescriptives; en particulier: la documentation doit être impersonnelle, objective, précise, formelle, littérale, courante, contractuelle, transversale, descriptive, définitive et déclarative. C'était une œuvre d'art, sans défaut, sublime, un triomphe rivalisé seulement par son échec monumental. Mon intention était d'établir des normes sans ambiguïté qui pourraient être objectivement vérifiées et appliquées par l'IA; cependant, un problème est devenu évident au fil du temps; en particulier, alors que certaines exigences pouvaient être objectivement vérifiées (telles que la Au lieu de répéter les normes brisées, un changement fondamental dans l’approche a été nécessaire. J’ai complètement réécrit le document et divisé le contenu en trois types: les normes (absolues et objectives), les pratiques (subjectives mais sans ambiguïté) et les lignes directrices (hautement subjectives et ambiguës), avec un lourd détour vers les lignes directrices. En mettant l’accent sur les orientations de haut niveau au lieu de règles rigides, et en encourageant un milieu entre les extrêmes opposés, les nouvelles directives offrent beaucoup de place à l’expression individuelle tout en décourageant les modes anti-patrons et d’échecs connus. Étiquette : sagesse raisonnable La documentation du répertoire doit être objective et fondée sur des faits, avec des références à la base de codes et à des sources externes, le cas échéant; cependant, la subjectivité sous forme d’expérience difficile est inestimable, car les faits seuls manquent du contexte pour être utiles, et éviter les expériences/perspectives uniques des contributeurs ne crée pas un environnement de soutien; par conséquent, la documentation devrait contenir un équilibre d’objectivité et de subjectivité. Too Academic: "FooSort expose la complexité informatique moyenne du cas O(N log N), comme l'a formellement prouvé Henderson (1984) par l'analyse amortisée utilisant des fonctions potentielles et des méthodes agrégées. la validation empirique a été réalisée par la simulation de Monte Carlo sur 10 000 ensembles de données uniformément distribués, donnant un intervalle de confiance de 95 % de [0,98N log N, 1,02N log N]. La solidité algorithmique a été évaluée par des pairs et publiée dans ACM Transactions (DOI:10.1145/12345)." (langage académique inutile) Too Poetic: "FooSort danse à travers les données comme un ballet gracieux, tissant élégamment des éléments dans leurs lieux légitimes. Il murmure l'efficacité à chaque tournant, une symphonie de comparaisons orchestrant l'ordre du chaos. Rapide comme l'éclair, belle comme un coucher de soleil, il transforme vos listes désordonnées en ensembles inébranlables d'harmonie pure." (Flowery métaphores obscure sens technique) Just Right: "FooSort classe N éléments en moyenne de temps O(N log N), ce qui le rend adapté à la plupart des cas d'utilisation. Cependant, il se dégrade à O(N2) sur les données triées par rapport, ce qui a causé des problèmes de production chez Company X lorsque les téléchargements des clients étaient généralement pré-triés. Pour cette raison, MergeSort est préféré pour les charges de travail de production malgré des facteurs constants légèrement pires." (Combine les faits objectifs avec l'expérience subjective et la conclusion raisonnable). Un équilibre entre objectivité et subjectivité garantit que la documentation reste précise et accessible, tout en créant un espace inclusif et de soutien pour les contributeurs. Équilibre du minimalisme avec l’adéquation Les contributeurs doivent inclure suffisamment d'informations pour éviter les coûts cachés de la documentation manquante, car le coût de stockage de quelques paragraphes supplémentaires (kilobytes) est beaucoup plus faible que le coût du contexte manquant (par exemple, des heures de débogage, des échecs de production, la réinvention de la roue); cependant, les détails inutiles vaincent le but en obscurcissant la vérité sous des détails inutiles; par conséquent, la documentation devrait omettre les informations inutiles. Too Minimal: "FooProvider cache les valeurs." (Contexte insuffisant sur le comportement, l'expiration ou les problèmes connus) Too Verbose : "FooProvider utilise en interne un ConcurrentHashMap instantié avec une capacité initiale de 16 et un facteur de charge de 0,75 pour stocker les valeurs cachées, qui sont elles-mêmes enveloppées dans un objet CacheEntry personnalisé contenant un timestamp 64-bit dérivé de System.nanoTime() pour des calculs d'expiration de haute précision, et sont évitables en utilisant une politique la moins récemment utilisée mise en œuvre via une liste synchronisée à double lien qui est traversée dans l'ordre inverse pendant les cycles de nettoyage déclenchés par un service ScheduledExecutorService fonctionnant sur un fil de daemon séparé. Just Right: "FooProvider cache les valeurs avec un TTL de 60 secondes en utilisant une politique d'exclusion de LRU. Le cache s'exécute sur un fil d'arrière-plan et peut causer des erreurs OOM sur les appareils Android limités par la mémoire." (contexte suffisant sur le comportement et les problèmes connus sans détails inutiles de mise en œuvre). L’équilibre entre le minimalisme (éviter les détails inutiles) et l’adéquation (fournir un contexte adéquat) garantit que la documentation reste utile et accessible sans obscurcir les informations critiques sous des détails de mise en œuvre excessifs. Ligne directrice : équilibre passé, présent et futur La documentation doit être liée à l'état actuel du dépôt, car documenter l'avenir risque d'être inexact à mesure que les plans changent, et documenter le passé peut confondre le dépôt avec des informations obsolètes; cependant, le contexte historique justifie souvent le présent tout en gardant l'histoire de se répéter, et la reconnaissance des opportunités pour les œuvres futures met en évidence les lacunes connues; par conséquent, le passé et le futur devraient être référencés là où cela est utile. Too Past-Focused : « Les dernières implémentations de cette méthode utilisaient la bibliothèque mathématique standard. Il y avait des problèmes avec le parser, mais ils ont été corrigés. » (Détails irréguliers sans contexte actionable) Too Future-Focused: "Dans le quatrième trimestre, nous prévoyons de réécrire l'analyste.Nous ferons cette méthode asynchrone dans v2.0." (Promesses sans contexte sur l'état actuel) Just Right : « Un analyseur personnalisé est utilisé parce que le testeur de bibliothèque standard a causé des régressions de performance dans v1.2. Cette méthode est synchrone, mais un support asynchrone peut être ajouté dans une future version (tracé par le numéro 123). » (état présent justifié par le contexte historique et les limitations connues reconnues avec la référence de suivi). L’équilibre entre la stabilité (documentation de ce qui existe) et le contexte (fourniture du contexte nécessaire) garantit que la documentation reste précise et utile tout en préservant l’historique utile et en reconnaissant les contraintes connues. Remarque : Lier les plans futurs aux références de suivi externes donne aux lecteurs un moyen de suivre et d’obtenir des mises à jour. Équilibre de précision avec simplicité La documentation doit être techniquement précise et précise, car des descriptions vagues conduisent à des malentendus et à une mauvaise utilisation ; cependant, des détails techniques excessifs peuvent obscurcir le concept de base et surcharger les lecteurs ; par conséquent, les contributeurs devraient fournir des explications précises sans complexité inutile. Trop vague: "FooProvider crée des objets quand vous en avez besoin." (Manque de précision technique sur le comportement) Le FooProvider utilise un mécanisme d'instantiation de modèle d'usine dans lequel chaque appel de la méthode d'accessoire déclenche l'allocation de la mémoire heap via le nouvel opérateur, entraînant la construction d'une instance Foo distincte avec sa propre adresse de mémoire. Just Right : "Le FooProvider crée une nouvelle instance de Foo à chaque appel." (descriptions techniques précises sans complexité inutile). Le fait de trouver un équilibre entre la précision (être techniquement correct) et la simplicité (être compréhensible) assure que la documentation transmet des informations précises sans surcharger les lecteurs avec des détails de mise en œuvre. Équilibre des formalités avec l’informalité La documentation devrait utiliser un langage professionnel qui maintient la crédibilité et la clarté, car le slang informel peut aliéner les lecteurs et réduire l'autorité perçue ; cependant, une expression trop académique ou formelle crée des barrières cognitives et éloigne les lecteurs ; par conséquent, les contributeurs devraient utiliser un anglais technique clair et standard. Trop informel : « Le compilateur de Kotlin est assez cool et ne fait que transformer votre code en bytecode ou quoi que ce soit pour différentes plates-formes comme JVM et choses. » Too Formal : « Le processus de compilation de Kotlin culmine par la génération de bytecode pour la machine virtuelle Java et d’objets analogues pour les substrats d’exécution alternatifs. » Just Right : "Kotlin compile pour le JVM et d'autres plates-formes (par exemple JS, native)." (Ton professionnel avec une terminologie claire et standard). L’équilibre entre la formalité (soutenir le professionnalisme) et l’informalité (être accessible) garantit que la documentation reste crédible et autoritaire tout en étant accessible aux ingénieurs généraux. Étiquette : groupes spécifiques La documentation nécessite souvent la référence des personnes ou des équipes derrière les décisions et les actions, car l’attribution fournit une responsabilité et un contexte ; cependant, les pronoms personnels (« nous », « moi », « nous », etc.) sont ambigus ; par conséquent, les contributeurs devraient utiliser des noms spécifiques d’individus ou de groupes lorsque cela est possible. Trop vague : « Le FooProvider est recommandé. » (Recommandé par qui?) Trop vague : « Nous avons décidé de supprimer les chauffeurs » (on ne sait pas à qui se réfère « nous ») Just Right: "L'équipe du noyau a décidé de supprimer les pilotes pour les performances en temps de fonctionnement." (attribution spécifique avec un raisonnement clair). L’équilibre entre l’attribution (assurant la responsabilité et le contexte) et la clarté (évitant les pronoms ambigus) assure une communication claire en utilisant des références de groupe spécifiques (par exemple « The Maintainers », « The Compiler Team », « The Security Workgroup ») plutôt que des pronoms vagues. Exception : les pronoms qui se réfèrent à l’utilisateur (par exemple « vous ») sont acceptables (relatifs à Balance Declarative et Imperative Tone). Équilibre : Tone déclarative et imperative La documentation devrait décrire le contenu du dépôt en indiquant ses comportements et propriétés, car cela maintient l'accent sur les artefacts qu'il contient; cependant, les procédures, les tutoriels et les guides peuvent être plus clairs lorsqu'ils sont écrits directement au lecteur avec des instructions impératives; par conséquent, les contributeurs devraient correspondre au ton au contexte. Too Imperative: "Vous devez configurer le FooProvider avant de l'utiliser.Vous devez d'abord appeler la méthode init()." (Commandes dans la documentation de référence) Too Declarative: "La cible //foo:bar génère des artefacts lorsqu'elle est exécutée." (descriptif passif dans un tutoriel où des conseils étape par étape sont nécessaires) Just Right: "Documentation de référence: FooProvider doit être configuré avant utilisation en appelant init(). Tutoriel: Générer les artefacts en exécutant bazel run //foo:bar." (Ton déclaratif pour les descriptions du système, ton impératif pour l'orientation procédurale). L’équilibre entre le déclaratif (définissant le système) et l’imperatif (guidant le lecteur) garantit que la documentation fournit des informations appropriées pour son contexte, la documentation de référence mettant l’accent sur les artefacts et les tutoriels fournissant des étapes claires. Équilibre entre confiance et humilité La documentation doit être écrite avec confiance lorsque le contenu est bien compris, car la couverture inutile sape l’autorité et crée le doute là où il ne devrait pas exister ; cependant, parler avec une conviction excessive lorsque la vérité est incertaine peut détourner la crédibilité ; par conséquent, les contributeurs devraient équilibrer la confiance avec l’humilité en reconnaissant les limites de la connaissance et en étant transparents sur leur incertitude. Trop hésitant: "FooProvider n'est probablement pas sans fil et il y a un petit risque d'échec du temps d'exécution." (sécurisation inutile sur le comportement connu) Trop confiant: "FooProvider fonctionnera certainement sous une pression de mémoire élevée." (fausse certitude sur le comportement non testé) Just Right: "FooProvider n'est pas sans fil. Le comportement sous pression de mémoire élevée est indéterminé et n'a pas été testé." (Confident sur les faits connus, honnête sur les inconnus). L’équilibre entre la confiance (établissement d’autorité) et l’humilité (reconnaissance des limites) garantit que la documentation maintient la crédibilité sans créer de doutes inutiles. Équilibre de jugement avec neutralité Les contributeurs devraient exercer leur jugement pour identifier les problèmes réels, les limites et les contraintes ; cependant, le langage de jugement qui attaque les systèmes, les plates-formes ou les contributeurs est inutile ; par conséquent, les contributeurs devraient se concentrer sur les descriptions factuelles sans accuser ou faire des caractérisations négatives étendues. Trop neutre : « Cette mise en œuvre fonctionne partout » (manque de jugement, ignorant les contraintes réelles) Too Judgmental: "Android est un système d'exploitation si sale qu'il ne peut même pas exécuter cela, aussi qui a écrit cette merde?" (attaque personnelle sur la plate-forme et les gens) Just Right : "Les appareils Android d'environ 2012 ont des limites de mémoire qui empêchent cette mise en œuvre de fonctionner comme prévu. L’équilibre entre le jugement (identification des problèmes réels et des contraintes) et la neutralité (évitement des attaques personnelles et de la culpabilité) garantit que la documentation fournit des informations précises et utiles sans recourir au jugement. Étiquette : équilibre avec respect Les contributeurs devraient montrer une considération pour le lecteur en reconnaissant les difficultés potentielles et en offrant des conseils de soutien, avec un langage apaisant utilisé de manière appropriée; toutefois, les affirmations et les hypothèses sur les capacités mentales ou physiques du lecteur peuvent être contre-productives, car elles traversent une frontière interpersonnelle critique; par conséquent, la documentation devrait offrir des options et des conseils, tout en donnant au lecteur le bénéfice du doute et en évitant les évaluations personnelles. Too Dismissive: "Ce comportement est évident et devrait être facile à comprendre." (Manque de considération pour les défis potentiels du lecteur) Trop présomptueux: "Vous trouverez probablement cet objet confus, et vous devriez probablement lire le guide de résolution de problèmes lorsque vous êtes coincé." (Fait des affirmations sur les capacités et l'expérience du lecteur) Just Right : « Cet objet ne met pas complètement en œuvre le contrat d'interface, et peut jeter des erreurs de manière inattendue. Les appelants peuvent vouloir utiliser Bar au lieu d'un service prêt à la production. La documentation complète est fournie dans le README. » (Reconnaît les limitations, offre des options, reste neutre et respectueux). Équilibrer la considération (reconnaître les défis potentiels) et le respect (éviter les présomptions sur le lecteur) garantit que la documentation fournit des conseils de soutien sans franchir les frontières interpersonnelles ou faire des hypothèses sur les capacités. Équilibre de l’abstraction avec la clarté La documentation devrait utiliser des abstractions appropriées qui correspondent à la conception du système, car l'abstraction cache les détails inutiles de la mise en œuvre et aide à la compréhension; cependant, le langage narratif et coloré peut obscurcir la vérité sous des couches d'indirections conceptuelles; par conséquent, les contributeurs devraient se concentrer sur des descriptions claires et directes du comportement du système. "Foo fonctionne comme une ceinture de transport, la première barre sur la ceinture est traitée, puis la prochaine, et ainsi de suite, jusqu'à ce que la ceinture soit vide, et l'opérateur va déjeuner quand il n'y a rien à faire." Too Imperative: "Foo enveloppe chaque objet de barre en tant que nœud, chacun avec un lien vers le nœud suivant / précédent, et tient une référence à un nœud (nœud racine marqué), puis suit récursivement les liens entre les nœuds pour les traiter dans l'ordre où ils ont été ajoutés. Just Right : "Foo traite les objets de barre à l'aide d'une queue FIFO et s'éloigne alors que la queue est vide.Foo utilise le motif pub-sub pour traiter les objets de barre de manière asynchrone." (Clear, descriptions directes avec une abstraction appropriée). Le fait de trouver un équilibre entre l’abstraction (cacher les détails de la mise en œuvre) et la clarté (éviter le poids narratif) garantit que la documentation explique clairement la mise en œuvre sans indirections conceptuelles inutiles. Documentation : Proximité de la documentation par la taille La documentation doit être distribuée près des artefacts auxquels elle se rapporte, car cela empêche les lecteurs d’être surchargés par des documents monolithiques et les aide à trouver des informations facilement ; cependant, la diffusion d’informations sur trop de documents obscurcit le sens et laisse les lecteurs sans une image cohérente ; par conséquent, les contributeurs devraient équilibrer la collocation avec la cohésion. Trop centralisé : le répertoire racine README contenant la documentation pour l'ensemble du repo. (surprenant, difficile à naviguer) Trop fragmenté: une lecture dans chaque paquet avec des détails de ce paquet seulement, sans aucun aperçu ni contexte sur la façon dont les paquets se rapportent. (Manque de cohésion) Just Right: Une README racine qui introduit la structure et la philosophie du dépôt, avec des READMEs plus petits granulaires pour les grands paquets. (distribution équilibrée avec un aperçu et des détails). Le fait de trouver un équilibre entre la colocation (la préservation de l’information à proximité de l’endroit où elle est importante) et la cohésion (fournir une image unifiée) garantit que la documentation est accessible sans être écrasante ou fragmentée. Remarque : Diviser un document dans un répertoire en plusieurs fichiers dans le même répertoire peut aider lorsque les informations sont au bon endroit, mais que le document devient trop grand. Pratique : Documentation appropriée à la portée La documentation granulaire (par exemple, Javadoc, commentaires en ligne) devrait se concentrer sur la composante à laquelle elle se rapporte ; tandis que la documentation de haut niveau (par exemple, READMEs, documents d’architecture) devrait se concentrer sur la façon dont les composants s’intègrent et se composent ensemble, et sur la manière dont ils s’intègrent dans le système plus large. Exemple positif : Javadoc expliquant les paramètres d'une fonction, la valeur de retour et les cas de bord. Exemple négatif : Javadoc expliquant l’ensemble de l’architecture système. Exemple positif : README expliquant comment les paquets interagissent et la philosophie globale de conception. Exemple négatif : README expliquant la mise en œuvre interne de chaque fonction. Cela garantit que les lecteurs peuvent trouver des informations appropriées au niveau approprié d'abstraction sans redondance ni défaut de portée. Étiquette : American English L'anglais américain doit être utilisé, sauf lorsque les conventions du domaine dictent le contraire (par exemple, référencement d'un objet Colours à partir d'un paquet tiers). Exemple : « Couleur » Exemple négatif : « couleur » Cela assure la cohérence dans toute la base de codes et s’aligne sur les conventions générales de l’ingénierie logicielle. Exception : Lorsque l’API/système sous-jacent documenté utilise une autre langue, la documentation doit correspondre. Étiquette : correct spelling Toute écriture doit être correcte. Exemple positif : « exigences » Exemple négatif : « demandes » Cela maintient le professionnalisme et évite les mauvaises communications. Standard : pas de comma après les abréviations Les commas doivent être omises après les abréviations. Un bon exemple : « etc ». Exemple négatif : « etc. » Cela réduit le trouble visuel. Étiquette : No Ampersands Le mot "et" doit être utilisé au lieu du symbole ampersand "&". Exemple positif : « Normes et pratiques » Exemple négatif : « Normes et pratiques » Cela adhère aux conventions d'écriture formelles et améliore l'accessibilité.
