Dit document is aangepast van Het verhaal van Jack Bradshaw . Stijlrichtlijnen Monotheïsche Effectieve documentatie is de hoeksteen van duurzame ontwikkeling; echter, de onvermijdelijkheid van teamgroei maakt het moeilijk om documentatie te schrijven als een team dat niet gefragmenteerd en inconsistent is; daarom is een zekere mate van coördinatie tussen bijdragers noodzakelijk. Zelfs solo-ingenieurs, die ooit een gratis pas hadden, moeten nu worstelen met de inconsistentie van door AI gegenereerde documentatie. Mijn eerste poging om dit probleem op te lossen culmineerde in de creatie van een Algemene Documentatie Standaard Document met 13 voorschrijvende regels; in het bijzonder: documentatie moet onpersoonlijk, objectief, nauwkeurig, formeel, letterlijk, actueel, contractueel, terse, beschrijvend, definitief en declaratief zijn. Het was een kunstwerk, foutloos, subliem, een triomf dat alleen door zijn monumentale mislukking rivaal. Mijn intentie was om onduidelijke normen op te stellen die objectief kunnen worden gecontroleerd en uitgevoerd door AI; echter, een probleem werd zichtbaar in de loop van de tijd; in het bijzonder, terwijl sommige vereisten objectief konden worden gecontroleerd (zoals lijstindeling), anderen waren inherent subjectief ( In plaats van te herhalen over gebroken normen, was een fundamentele verschuiving in de benadering vereist. Ik heb het document volledig opnieuw geschreven en de inhoud in drie typen verdeeld: normen (absolute en objectieve), praktijken (subjectief maar ondubbelzinnig) en richtlijnen (zeer subjectief en dubbelzinnig), met een zware verschuiving naar richtlijnen. Door te focussen op leidraad op hoog niveau in plaats van rigide regels, en een middenveld tussen tegenstrijdige uitersten aan te moedigen, bieden de nieuwe richtlijnen voldoende ruimte voor individuele expressie, terwijl ze bekende anti-patterns en mislukkingsmodi ontmoedigen. Reacties op: Reasoned Wisdom Repository documentatie moet objectief en op feiten gebaseerd zijn, met verwijzingen naar de codebase en externe bronnen waar passend; echter, subjectiviteit in de vorm van hard verworven ervaring is van onschatbare waarde, omdat feiten alleen de context ontbreken om nuttig te zijn, en het vermijden van de unieke ervaringen / perspectieven van bijdragers creëert geen ondersteunende omgeving; daarom moet documentatie een evenwicht van objectiviteit met subjectiviteit bevatten. Too Academic: "FooSort toont O(N log N) gemiddelde-case computationele complexiteit, zoals formeel bewezen door Henderson (1984) via geamortiseerde analyse met behulp van potentiële functies en geaggregeerde methoden. empirische validatie werd uitgevoerd door middel van Monte Carlo-simulatie over 10.000 gelijkmatig verdeelde datasets, waardoor een 95% vertrouwensinterval van [0.98N log N, 1.02N log N]. De algoritmische soundness is peer-reviewed en gepubliceerd in ACM Transactions (DOI:10.1145/12345)." Too Poetic: "FooSort danst door data als een gracieus ballet, elegant weeft elementen in hun rechtmatige plaatsen. Het fluistert efficiëntie op elke beurt, een symfonie van vergelijkingen die orde uit chaos orchestreert.Snel als bliksem, mooi als zonsondergang, het transformeert uw rommelige lijsten in onbewerkte array's van pure harmonie." (Flowery metafoor verduisterde technische betekenis) Just Right: "FooSort sorteert N items in O(N log N) gemiddelde tijd, waardoor het geschikt is voor de meeste gebruiksgevallen. echter, het degradeert naar O(N2) op gerapporteerde gerangschikt gegevens, wat productieproblemen veroorzaakte bij Company X toen klant uploads waren meestal vooraf gerangschikt. Om die reden, MergeSort is de voorkeur voor productie-werkbelastingen ondanks iets slechtere constante factoren." (Kombineert objectieve feiten met subjectieve ervaring en redelijke conclusie). Het vinden van een evenwicht tussen objectiviteit en subjectiviteit zorgt ervoor dat documentatie nauwkeurig en toegankelijk blijft, terwijl een inclusieve en ondersteunende ruimte wordt gecreëerd voor bijdragers. Richtlijn: evenwicht minimalisme met voldoendeheid Bijdrager moet voldoende informatie opnemen om de verborgen kosten van ontbrekende documentatie te vermijden, omdat de kosten van het opslaan van een paar extra paragraafjes (kilobytes) veel lager zijn dan de kosten van ontbrekende context (bijv. uren debuggen, productiefouten, het opnieuw uitvinden van het wiel); onnodige details verslaan echter het doel door de waarheid onder onnodige details te verdoezelen; daarom moet documentatie overbodige informatie weglaten. Too Minimal: "FooProvider cache waarden." (Onvoldoende context over gedrag, vervaldatum of bekende problemen) Too Verbose: "FooProvider gebruikt intern een ConcurrentHashMap geïnstantieerd met een initiële capaciteit van 16 en een laadfactor van 0,75 om de gecachteerde waarden op te slaan, die zelf worden verpakt in een aangepast CacheEntry-object dat een 64-bits tijdstempel bevat afgeleid van System.nanoTime() voor hoge nauwkeurigheid vervalberingen, en kunnen worden verwijderd met behulp van een minst recent gebruikte beleid geïmplementeerd via een gesynchroniseerde dubbel gekoppelde lijst die wordt doorgegeven in omgekeerde volgorde tijdens schoonmaakcycli die worden veroorzaakt door een ScheduledExecutorService die op een afzonderlijke daemon thread draait. Just Right: "FooProvider cacheert waarden met een TTL van 60 seconden met behulp van een LRU-uitwijzingsbeleid.De cache wordt uitgevoerd op een achtergronddraad en kan OOM-fouten veroorzaken op geheugenbeperkte Android-apparaten." (voldoende context over gedrag en bekende problemen zonder onnodige implementatiedetails). Het vinden van een evenwicht tussen minimalisme (het vermijden van onnodige details) en voldoendeheid (het verstrekken van een adequate context) zorgt ervoor dat documentatie nuttig en toegankelijk blijft zonder kritische informatie te verdoezelen onder overmatige implementatiedetails. Richtlijn: balanceren verleden, heden en toekomst Documentatie moet betrekking hebben op de huidige toestand van het repository, zoals het documenteren van de toekomst riskeert onnauwkeurigheid als plannen veranderen, en het documenteren van het verleden kan het repository verwarren met verouderde informatie; echter, historische context rechtvaardigt vaak het heden, terwijl het beschermen tegen de herhaling van de geschiedenis, en het erkennen van kansen voor toekomstige werken benadrukt bekende tekortkomingen; daarom moet het verleden en de toekomst worden verwezenlijkt waar nuttig. Too Past-Focused: "Voorgaande implementaties van deze methode gebruikten de standaard wiskundige bibliotheek. er waren problemen met de parser, maar ze werden opgelost." (Irrelevant details zonder handige context) Too Future-Focused: "In Q4 zijn we van plan om de parser opnieuw te schrijven. we zullen deze methode asynchrone maken in v2.0." (Belofte zonder context over de huidige staat) Just Right: "Een aangepaste analyser wordt gebruikt omdat de standaard bibliotheek analyser veroorzaakte prestatie regressie in v1.2. Deze methode is synchrone, maar asynchrone ondersteuning kan worden toegevoegd in een toekomstige release (getraceerd door issue #123)." (Present state gerechtvaardigd door historische context en bekende beperkingen erkend met tracking reference). Het vinden van een evenwicht tussen stabiliteit (het documenteren van wat er bestaat) en context (het verstrekken van de nodige achtergrond) zorgt ervoor dat documentatie nauwkeurig en nuttig blijft, terwijl nuttige geschiedenis wordt bewaard en bekende beperkingen worden erkend. Opmerking: Het koppelen van toekomstige plannen aan externe trackingreferenties geeft lezers een manier om te volgen en updates te krijgen. Richtlijn: Balance Precision met Simplicity Documentatie moet technisch nauwkeurig en nauwkeurig zijn, omdat vage beschrijvingen leiden tot misverstanden en onjuist gebruik; overmatige technische details kunnen echter het kernconcept verdoezelen en lezers overweldigen; bijdragen moeten daarom nauwkeurige verklaringen bieden zonder onnodige complexiteit. Too Vague: "FooProvider maakt objecten wanneer je ze nodig hebt." (Het ontbreekt aan technische precisie over gedrag) Ook gedetailleerd: "De FooProvider maakt gebruik van een fabriekspatroon instantiatie mechanisme waarbij elke aanroeping van de accessoire methode trigger de toewijzing van heap geheugen via de nieuwe operator, wat resulteert in de bouw van een onderscheidende Foo instantie met zijn eigen geheugen adres." (Overmatige technische details verduisteren eenvoudig gedrag) Just Right: "De FooProvider creëert een nieuwe instantie van Foo op elke oproep." (Precieze technische beschrijving zonder onnodige complexiteit). Het vinden van een evenwicht tussen nauwkeurigheid (technisch correct) en eenvoud (begrijpelijk) zorgt ervoor dat documentatie nauwkeurige informatie overbrengt zonder lezers te overweldigen met implementatie minutiae. Richtlijn: evenwicht tussen formaliteit en informaliteit Documentatie moet professionele taal gebruiken die de geloofwaardigheid en helderheid behouden, omdat informele slang lezers kan vervreemden en waargenomen autoriteit kan verminderen; overmatige academische of formele uitdrukking creëert echter cognitieve barrières en verwijdert lezers; daarom moeten bijdragers duidelijk, standaard technisch Engels gebruiken. Too Informal: "Kotlin's compiler is behoorlijk cool en verandert je code gewoon in bytecode of wat dan ook voor verschillende platforms zoals JVM en stuff." (Casual slang ondermijnt de geloofwaardigheid) "Het compilatieproces van Kotlin culmineert in de generatie van bytecode voor de Java Virtual Machine en analoge artefacten voor alternatieve uitvoeringssubstraten." Just Right: "Kotlin compileert naar de JVM en andere platforms (bijv. JS, native)." (Professionele toon met duidelijke, standaard terminologie). Het vinden van een evenwicht tussen formaliteit (professionalisme behouden) en informaliteit (toegankelijk zijn) zorgt ervoor dat documentatie geloofwaardig en gezaghebbende blijft, terwijl het toegankelijk is voor algemene ingenieurs. Richtlijn: Specifieke groepsreferenties Documentatie vereist vaak het verwijzen naar de mensen of teams achter beslissingen en acties, omdat toewijzing verantwoordelijkheid en context biedt; echter, de persoonlijke voorvoegwoorden ("wij", "ik", "ons", enz.) zijn dubbelzinnig; daarom moeten bijdragers specifieke individuele / groepsnamen gebruiken waar mogelijk. Too Vague: "De FooProvider wordt aanbevolen." (Aanbevolen door wie?) Too Vague: "We besloten om de chauffeurs te verwijderen." (Onduidelijk wie "wij" verwijst naar) Just Right: "Het Kernel-team besloot de drivers te verwijderen voor runtime-prestaties." (Specifieke toewijzing met duidelijke redenering). Het vinden van een evenwicht tussen toewijzing (verantwoordelijkheid en context) en duidelijkheid (duizelig pronoom vermijden) zorgt voor duidelijke communicatie door gebruik te maken van specifieke groepsreferenties (bijv. "The Maintainers", "The Compiler Team", "The Security Workgroup") in plaats van vage pronooms. Uitzondering: voorvoegwoorden die verwijzen naar de gebruiker (bijv. "u") zijn acceptabel (gerelateerd aan Balance Declarative en Imperative Tone). Balance Declarative en Imperative Tone Documentatie moet de inhoud van het repository beschrijven door zijn gedrag en eigenschappen te vermelden, omdat dit de focus op de artefacten houdt die het bevat; procedures, tutorials en gidsen kunnen echter duidelijker zijn wanneer ze rechtstreeks aan de lezer worden geschreven met dwingende instructies; daarom moeten bijdragers de toon aan de context passen. Too Imperative: "Je moet de FooProvider configureren voordat je het gebruikt.Je moet eerst de init() methode bellen." (opdrachten in referentiedocumentatie) Too Declarative: "De //foo:bar target genereert artefacten wanneer uitgevoerd." (Passieve beschrijving in een tutorial waar stap-voor-stap begeleiding nodig is) Just Right: "Referentiedocumentatie: FooProvider moet vóór gebruik worden geconfigureerd door init() te bellen. Tutorial: Genereer de artefacten door bazel run //foo:bar uit te voeren." (Declaratieve toon voor systeembeschrijvingen, imperatieve toon voor procedurele begeleiding). Het vinden van een evenwicht tussen declaratief (dat het systeem definieert) en imperatief (dat de lezer begeleidt) zorgt ervoor dat documentatie passende informatie biedt voor de context, met referentiedocumentatie die zich richt op artefacten en tutorials die duidelijke stappen bieden. Richtlijn: Balance vertrouwen en nederigheid Documentatie moet met vertrouwen worden geschreven wanneer de inhoud goed wordt begrepen, omdat onnodige afscherming autoriteit ondermijnt en twijfel creëert waar er geen zou moeten bestaan; echter, met overdreven overtuiging spreken wanneer de waarheid onzeker is, kan de geloofwaardigheid afleiden; bijdragen moet daarom vertrouwen met nederigheid in evenwicht brengen door de beperkingen van kennis te erkennen en transparant te zijn over hun onzekerheid. Te aarzelend: "FooProvider is waarschijnlijk niet thread-safe en er is een klein risico op runtime-falen." (Onnodige hedging over bekend gedrag) Te zelfverzekerd: "FooProvider zal zeker werken onder hoge geheugendruk." (valse zekerheid over niet-getest gedrag) Just Right: "FooProvider is niet thread-safe.Het gedrag onder hoge geheugendruk is niet gedefinieerd en is niet getest." (Vertrouwend over bekende feiten, eerlijk over onbekende). Het vinden van een evenwicht tussen vertrouwen (instelling van autoriteit) en nederigheid (herkenning van grenzen) zorgt ervoor dat documentatie de geloofwaardigheid behoudt zonder onnodige twijfel te creëren. Richtlijn: Balance Judgment met Neutraliteit Bijdragers moeten beoordeling uitoefenen om echte problemen, beperkingen en beperkingen te identificeren; echter, beoordelingstaal die systemen, platforms of bijdragers aanvalt, is nutteloos; bijdragenaren moeten zich daarom richten op feitelijke beschrijvingen zonder schuld te geven of omvangrijke negatieve karakterisaties te maken. Te neutraal: "Deze implementatie werkt overal." (geeft oordeel, negeert echte beperkingen) Too Judgmental: "Android is zo'n vuil besturingssysteem dat het dit niet eens kan draaien, ook wie schreef deze shit?" (Persoonlijke aanval op platform en mensen) Just Right: "Android-apparaten rond 2012 hebben geheugenbeperkingen die voorkomen dat deze implementatie werkt zoals bedoeld. de Foo-implementatie werkt niet op Android." (geluid oordeel met specifieke, informatieve en feitelijke beschrijvingen). Het vinden van een evenwicht tussen oordeel (het identificeren van echte problemen en beperkingen) en neutraliteit (het vermijden van persoonlijke aanvallen en schuldgevoelens) zorgt ervoor dat documentatie nauwkeurige en nuttige informatie biedt zonder toevlucht te nemen tot oordeel. Richtlijn: Balance overweging met respect Bijdragever dient rekening te houden met de lezer door potentiële moeilijkheden te erkennen en ondersteunende begeleiding aan te bieden, met gepaste verzachtende taal; echter, beweringen en veronderstellingen over de mentale of fysieke capaciteiten van de lezer kunnen contraproductief zijn, omdat ze een kritische interpersoonlijke grens overschrijden; daarom moet documentatie opties en advies bieden, terwijl de lezer het voordeel van de twijfel geeft en persoonlijke beoordelingen vermijdt. Too Dismissive: "Dit gedrag is voor de hand liggend en moet gemakkelijk te begrijpen zijn." (geeft rekening te houden met de potentiële uitdagingen van de lezer) Te vermoedelijk: "Je zult dit object waarschijnlijk verwarrend vinden, en je zou waarschijnlijk de gids voor het oplossen van problemen moeten lezen als je vastzit." (Maakt beweringen over de mogelijkheden en ervaring van de lezer) Just Right: "Dit object implementeert niet volledig de interface contract, en kan fouten gooien op onverwachte manieren. oproepers kunnen Bar willen gebruiken in plaats van voor een productie klaar service. volledige documentatie wordt verstrekt in de README." (Hij erkent beperkingen, biedt opties, blijft neutraal en respectvol). Het vinden van een evenwicht tussen overweging (herkenning van mogelijke uitdagingen) en respect (het vermijden van veronderstellingen over de lezer) zorgt ervoor dat documentatie ondersteunende begeleiding biedt zonder tussenpersoonlijke grenzen te overschrijden of veronderstellingen te maken over mogelijkheden. Richtlijn: Balance abstractie met helderheid Documentatie moet geschikte abstracties gebruiken die overeenkomen met het ontwerp van het systeem, omdat abstractie onnodige implementatiedetails verbergt en begrip helpt; echter, narratieve en kleurrijke taal kan de waarheid verdoezelen onder lagen van conceptuele indirectie; daarom moeten bijdragen zich richten op duidelijke, directe beschrijvingen van systeemgedrag. "Foo werkt als een transportband, de eerste Bar op de gordel wordt verwerkt, dan de volgende, enzovoort, totdat de gordel leeg is en de operator gaat lunchen wanneer er niets te doen is." Too Imperative: "Foo wraps elk Bar-object als een knoop, elk met een link naar de volgende / vorige knoop, en houdt een verwijzing naar een knoop (gemarkeerde wortel knoop), vervolgens recursief volgt de links tussen knooppunten om ze te verwerken in de volgorde waarin ze werden toegevoegd. Just Right: "Foo verwerkt Bar-objecten met behulp van een FIFO-race, en vervalt terwijl de rij leeg is. Foo gebruikt het pub-sub-patroon om Bar-objecten asynchroon te verwerken." (Clear, directe beschrijvingen met passende abstractie). Het vinden van een evenwicht tussen abstractie (verbergen van implementatiedetails) en duidelijkheid (vermijden van narratief gewicht) zorgt ervoor dat documentatie de implementatie duidelijk verklaart zonder onnodige conceptuele indirectie. Richtlijn: Balance documentatie nabijheid met grootte Documentatie moet worden verspreid in de buurt van de artefacten waarnaar het betrekking heeft, omdat dit voorkomt dat lezers worden overweldigd door monolithische documenten en hen helpt informatie gemakkelijk te vinden; echter, het verspreiden van informatie over te veel documenten verduistert de betekenis en laat lezers zonder een samenhangend beeld; daarom moeten bijdragers collocatie in evenwicht brengen met samenhang. Te gecentraliseerd: het root repository README bevat documentatie voor de hele repo. (Overweldigend, moeilijk te navigeren) Te gefragmenteerd: een README in elk pakket met details van dat pakket alleen, zonder overzicht of context over hoe pakketten releren. Just Right: Een root README die de repository structuur en filosofie introduceert, met kleinere granulaire READMEs voor grote pakketten. Door een evenwicht te vinden tussen collocatie (informatie dicht bij waar het telt) en samenhang (een verenigd beeld te bieden) is documentatie toegankelijk zonder overweldigend of gefragmenteerd te worden. Opmerking: Het splitsen van een document in een directory in meerdere bestanden in dezelfde directory kan helpen wanneer de informatie op de juiste plaats is, maar het document te groot wordt. Praktijk: toepasselijke documentatie Granulaire documentatie (bijv. Javadoc, inline opmerkingen) moet zich richten op de component waarnaar ze betrekking hebben; terwijl documentatie op hoog niveau (bijv. READMEs, architectuurdocumenten) zich moet richten op de manier waarop componenten integreren en samenstellen en hoe ze in het bredere systeem passen. Positief voorbeeld: Javadoc die de parameters van een functie, de retourwaarde en de randgevallen verklaart. Negatief voorbeeld: Javadoc verklaart de hele systeemarchitectuur. Positief voorbeeld: README waarin wordt uitgelegd hoe pakketten samenwerken en de algemene ontwerpfilosofie. Negatief voorbeeld: README waarin de interne implementatie van elke functie wordt uitgelegd. Dit zorgt ervoor dat lezers de juiste informatie kunnen vinden op het juiste niveau van abstractie zonder redundantie of mismatch van de reikwijdte. Standaard: Amerikaans Engels Amerikaans Engels moet worden gebruikt, tenzij domeinconventies anders bepalen (bijv. verwijzen naar een Colours-object uit een pakket van derden). Positief voorbeeld: “kleur” Negatief voorbeeld: “kleur” Dit zorgt voor consistentie in de codebase en is in lijn met algemene software engineering-conventies. Uitzondering: Wanneer het onderliggende API/systeem dat wordt gedocumenteerd een andere taal gebruikt, moet de documentatie overeenkomen. Standaard: correcte spelling Alle spelling moet correct zijn. Positief voorbeeld: “vereisten” Negatief voorbeeld: “vereisten” Dit zorgt voor professionalisme en voorkomt miscommunicatie. Standard: geen comma na afkortingen Commas moeten na afkortingen worden weggelaten. Een positief voorbeeld: “etc.” Een negatief voorbeeld: “etc.” Dit vermindert visuele verwarring. Standaard: No Ampersands Het woord "en" moet worden gebruikt in plaats van het ampersand symbool "&". Positief voorbeeld: "Standaarden en praktijken" Negatief voorbeeld: "Standaarden en praktijken" Dit houdt zich aan formele schrijfconventies en verbetert de toegankelijkheid.
