Detta dokument har anpassats från Från Jack Bradshaw . Stildirektiv Monorepo Effektiv dokumentation är hörnstenen i hållbar utveckling; emellertid gör oundvikligheten av teamutveckling det svårt att skriva dokumentation som ett team som inte är fragmenterat och inkonsekvent; därför är en viss grad av samordning mellan bidragsgivare nödvändig. även soloingenjörer, som en gång hade ett fritt pass, måste nu kämpa med inkonsekvensen av AI-genererad dokumentation. Mitt första försök att lösa detta problem kulminerade i skapandet av ett allmänt dokumentationsstandarddokument som innehöll 13 föreskrivande regler; specifikt: dokumentation måste vara opersonlig, objektiv, exakt, formell, bokstavlig, aktuell, avtalsmässig, terse, beskrivande, definitiv och deklarativ. Det var ett konstverk, felfritt, sublimt, en triumf rivaliserad endast av dess monumentala misslyckande. Min avsikt var att etablera otvetydiga standarder som kunde verifieras och verkställas objektivt av AI; emellertid blev ett problem uppenbart över tiden; specifikt, medan vissa krav kunde verifieras objektivt (som listformatering), var andra i sig subjektiva (intresse, definitivitet etc.) och visade sig vara svåra att utvärdera; dessutom kvävade sådana stela regler den I stället för att iterera om brutna standarder krävdes det ett grundläggande skifte i tillvägagångssättet. Jag omskrivde dokumentet helt och hållet och delade upp innehållet i tre typer: standarder (absolut och objektivt), metoder (subjektivt men otvetydigt) och riktlinjer (högst subjektivt och tvetydigt), med en tung sväng mot riktlinjerna. Genom att fokusera på vägledning på hög nivå i stället för stela regler och uppmuntra en mellanting mellan motsatta extremer, ger de nya riktlinjerna gott om utrymme för individuellt uttryck samtidigt som de avskräcker kända anti-mönster och misslyckande lägen. Etikettarkiv: förnuftig visdom Repository-dokumentationen måste vara objektiv och faktabaserad, med hänvisningar till kodbasen och externa källor där så är lämpligt; dock är subjektivitet i form av hårt förvärvad erfarenhet ovärderlig, eftersom fakta ensamma saknar kontext för att vara användbar, och att undvika de unika erfarenheterna/perspektiven hos bidragsgivarna skapar inte en stödjande miljö; därför bör dokumentationen innehålla en balans mellan objektivitet och subjektivitet. Too Academic: "FooSort exponerar O(N log N) genomsnittliga fall beräkningskomplexitet, som formellt bevisas av Henderson (1984) via amorterad analys med hjälp av potentiella funktioner och aggregerade metoder. empirisk validering genomfördes genom Monte Carlo simulering över 10 000 jämnt fördelade dataset, vilket ger ett 95% konfidensintervall av [0.98N log N, 1.02N log N]. Algoritmisk soundness har peer-reviewed och publicerats i ACM Transactions (DOI:10.1145/12345)." Too Poetic: "FooSort dansar genom data som en graciös ballett, elegant vävande element till sina rättmätiga platser. Det viskar effektivitet vid varje tur, en symfoni av jämförelser som orkestrerar ordning från kaos. Snabbt som blixten, vacker som en solnedgång, det förvandlar dina röriga listor till orubbliga uppsättningar av ren harmoni." Just Right: "FooSort sorterar N-objekt i O(N log N) genomsnittlig tid, vilket gör det lämpligt för de flesta användningsfall. Men det degraderar till O(N2) på rapporterade sorterade data, vilket orsakade produktionsproblem på Company X när kunduppladdningar vanligtvis var försorterade. Av denna anledning föredras MergeSort för produktionsarbetsbelastningar trots något sämre konstanta faktorer." (Kombinerar objektiva fakta med subjektiv erfarenhet och motiverad slutsats). En balans mellan objektivitet och subjektivitet säkerställer att dokumentationen förblir korrekt och tillgänglig, samtidigt som det skapas ett inkluderande och stödjande utrymme för bidragsgivarna. Riktlinje: Balansera minimalism med tillräcklighet Bidragsgivarna måste inkludera tillräckligt med information för att undvika de dolda kostnaderna för saknad dokumentation, eftersom kostnaden för att lagra några extra stycken (kilobytes) är mycket lägre än kostnaden för saknad sammanhang (t.ex. timmar av debugging, produktionsfel, att uppfinna hjulet igen); men onödiga detaljer besegrar syftet genom att dölja sanningen under onödiga detaljer. För liten: "FooProvider cache värden." (Otillräckligt sammanhang om beteende, utgång eller kända problem) Too Verbose: "FooProvider använder internt en ConcurrentHashMap instantiated med en initial kapacitet på 16 och en belastningsfaktor på 0,75 för att lagra de cachade värdena, som själva är inslagna i ett anpassat CacheEntry-objekt som innehåller en 64-bitars tidsstämpel som härrör från System.nanoTime() för hög precision för utgångsberäkningar, och är evictable med hjälp av en minst nyligen använt policy genomförd via en synkroniserad dubbellänkad lista som korsas i omvänd ordning under rengöringscykler utlöses av en ScheduledExecutorService som körs på en separat daemon thread. Just Right: "FooProvider cachar värden med en 60-sekunders TTL med hjälp av en LRU-utvisningspolicy. Cachen körs på en bakgrundsträng och kan orsaka OOM-fel på minnesbegränsade Android-enheter." (Tillräckligt sammanhang om beteende och kända problem utan onödiga implementeringsdetaljer). Att hitta en balans mellan minimalism (undvikande av onödiga detaljer) och tillräcklighet (tillhandahållande av adekvat sammanhang) säkerställer att dokumentationen förblir användbar och tillgänglig utan att dölja kritisk information under överdriven implementeringsdetaljer. Riktlinje: Balansera förflutna, nutid och framtid Dokumentation bör relatera till det nuvarande tillståndet i arkivet, eftersom dokumentation av framtiden riskerar felaktigheter när planer ändras, och dokumentation av det förflutna kan förvirra arkivet med föråldrad information; dock rättfärdigar historiskt sammanhang ofta nuet samtidigt som man skyddar mot att historien upprepar sig, och erkännande av möjligheter för framtida verk belyser kända brister; därför bör det förflutna och framtiden hänvisas där det är användbart. Too Past-Focused: "Förra implementeringar av denna metod använde det vanliga matematiska biblioteket. Det fanns problem med parseren men de fixades." (Irrelevanta detaljer utan handlingsbart sammanhang) Too Future-Focused: "I Q4 planerar vi att skriva om analysen. Vi kommer att göra denna metod asynkron i v2.0." (Löften utan sammanhang om nuvarande tillstånd) Just Right: "En anpassad parser används eftersom standardbiblioteksparser orsakade prestanda regressioner i v1.2. Denna metod är synkron, men asynkron support kan läggas till i en framtida utgåva (spåras av utgåva #123)." (nuvarande tillstånd motiveras av historiskt sammanhang och kända begränsningar erkänns med spårningsreferens). Att hitta en balans mellan stabilitet (dokumentera vad som finns) och sammanhang (tillhandahålla nödvändig bakgrund) säkerställer att dokumentationen förblir korrekt och användbar samtidigt som användbar historia bevaras och kända begränsningar erkänns. Obs!: Att länka framtida planer till externa spårningsreferenser ger läsarna ett sätt att följa och få uppdateringar. Riktlinje: Balansera precision med enkelhet Dokumentationen måste vara tekniskt korrekt och exakt, eftersom vaga beskrivningar leder till missförstånd och felaktig användning; överdriven teknisk detalj kan emellertid fördunkla kärnkonceptet och överväldiga läsarna; Därför bör bidragsgivare ge exakta förklaringar utan onödig komplexitet. Too Vague: "FooProvider gör objekt när du behöver dem." (saknar teknisk precision om beteende) För detaljerad: "FooProvider använder en fabriksmönster instantiering mekanism där varje åberopande av tillbehörsmetoden utlöser tilldelningen av heap-minne via den nya operatören, vilket resulterar i konstruktionen av en distinkt Foo-instans med sin egen minnesadress." (Överdriven teknisk detalj döljer enkelt beteende) Just Right: "FooProvider skapar en ny instans av Foo på varje samtal." (Exakt teknisk beskrivning utan onödig komplexitet). Att hitta en balans mellan precision (att vara tekniskt korrekt) och enkelhet (att vara begriplig) säkerställer att dokumentationen överför korrekt information utan att överväldiga läsarna med implementering minutiae. Riktlinje: Balansera formalitet med informalitet Dokumentation bör använda professionellt språk som upprätthåller trovärdighet och tydlighet, eftersom informell slang kan avlägsna läsare och minska uppfattad auktoritet; emellertid skapar alltför akademisk eller formell frasering kognitiva hinder och avlägsnar läsare; Därför bör bidragsgivare använda tydlig, standard teknisk engelska. För informell: "Kotlins kompilator är ganska cool och omvandlar bara din kod till bytecode eller vad som helst för olika plattformar som JVM och saker." (Casual slang undergräver trovärdighet) För formell: "Kotlins kompileringsprocess kulminerar i generering av bytekod för Java Virtual Machine och analoga artefakter för alternativa utförande substrat." (Över akademisk frasning fördunklar innebörden) Just Right: "Kotlin sammanställer till JVM och andra plattformar (t.ex. JS, native)." (Professionell ton med tydlig, standardterminologi). Att hitta en balans mellan formalitet (underhålla professionalism) och informalitet (att vara tillgänglig) säkerställer att dokumentationen förblir trovärdig och auktoritativ samtidigt som den är tillgänglig för allmänna ingenjörer. Riktlinjer: Särskilda referenser för grupper Dokumentation kräver ofta att man refererar till de personer eller team som står bakom beslut och handlingar, eftersom attribut ger ansvarsskyldighet och sammanhang; emellertid är de personliga smeknamnen ("vi", "jag", "oss", etc.) tvetydiga; därför bör bidragsgivare använda specifika individuella/gruppnamn där det är möjligt. För vagt: "FooProvider rekommenderas" (Rekommenderas av vem?) Too Vague: "Vi bestämde oss för att ta bort förarna." (oklart vem "vi" hänvisar till) Just Right: "Kernelteamet bestämde sig för att ta bort drivrutinerna för löptidsprestanda." (Specifik attribut med tydlig resonemang). Att hitta en balans mellan attribut (tillhandahålla ansvarsskyldighet och sammanhang) och tydlighet (undvika tvetydiga pronominer) säkerställer tydlig kommunikation genom att använda specifika gruppreferenser (t.ex. "The Maintainers", "The Compiler Team", "The Security Workgroup") snarare än vaga pronominer. Undantag: Pronumerationer som hänvisar till användaren (t.ex. "du") är acceptabla (relaterade till balansdeklarativ och imperativ ton). Riktlinje: Balansdeklarativ och imperativ ton Dokumentationen bör beskriva innehållet i arkivet genom att ange dess beteenden och egenskaper, eftersom detta håller fokus på de artefakter som den innehåller, men procedurer, handledning och guider kan vara tydligare när de skrivs direkt till läsaren med imperativa instruktioner; Därför bör bidragsgivare matcha tonen till sammanhanget. Too Imperative: "Du måste konfigurera FooProvider innan du använder den. Du bör ringa init() metoden först." (kommandon i referensdokumentation) Too Declarative: " //foo:bar-målet genererar artefakter när det utförs." (Passiv beskrivning i en handledning där steg för steg vägledning behövs) Just Right: "Referensdokumentation: FooProvider måste konfigureras före användning genom att ringa init(). Tutorial: Generera artefakterna genom att köra bazel run //foo:bar." (Declarative ton för systembeskrivningar, imperativ ton för procedurledning). Att hitta en balans mellan deklarativ (definierar systemet) och imperativ (guider läsaren) säkerställer att dokumentationen ger lämplig information för sitt sammanhang, med referensdokumentation som fokuserar på artefakter och handledning som ger tydliga handlingsbara steg. Riktlinje: Balansera förtroende och ödmjukhet Dokumentation bör skrivas med förtroende när innehållet är väl förstått, eftersom onödig säkring undergräver auktoritet och skapar tvivel där ingen borde existera; men att tala med överdriven övertygelse när sanningen är osäker kan avskräcka från trovärdighet; Därför bör bidragsgivare balansera förtroende med ödmjukhet genom att erkänna kunskapens begränsningar och vara transparenta om deras osäkerhet. För osäker: "FooProvider är förmodligen inte tråd-säker och det finns en liten risk för runtime misslyckande." (Onödig säkring om känt beteende) För säker: "FooProvider kommer definitivt att fungera under högt minnestryck." (Falsk säkerhet om otestat beteende) Just Right: "FooProvider är inte tråd-säker.Beteendet under högt minnestryck är odefinierat och har inte testats." (Troende om kända fakta, ärlig om okända). Att hitta en balans mellan förtroende (en myndighetsuppbyggnad) och ödmjukhet (att erkänna gränser) säkerställer att dokumentationen bibehåller trovärdigheten utan att skapa onödiga tvivel. Riktlinje: Balansera dom med neutralitet Bidragsgivare bör utöva bedömning för att identifiera verkliga problem, begränsningar och begränsningar; emellertid är bedömningsspråk som attackerar system, plattformar eller bidragsgivare värdelös; Därför bör bidragsgivare fokusera på faktiska beskrivningar utan att tilldela skuld eller göra omfattande negativa karakteriseringar. För neutralt: "Denna implementering fungerar överallt." (saknar bedömning, ignorerar verkliga begränsningar) Too Judgmental: "Android är ett så jävla operativsystem att det inte ens kan köra detta, också vem skrev denna skit?" (personligt angrepp på plattform och människor) Just Right: "Android-enheter runt 2012 har minnesbegränsningar som hindrar denna implementering från att fungera som avsett. Foo-implementeringen fungerar inte på Android." (ljuddom med specifika, informativa och faktiska beskrivningar). Att hitta en balans mellan bedömning (identifiering av verkliga problem och begränsningar) och neutralitet (undvikande av personliga attacker och skuld) säkerställer att dokumentationen ger korrekt och användbar information utan att tillgripa bedömning. Etikettarkiv: balansera med respekt Bidragsgivare bör visa hänsyn till läsaren genom att erkänna potentiella svårigheter och erbjuda stödjande vägledning, med mjukgörande språk som används på lämpligt sätt; emellertid kan påståenden och antaganden om läsarens mentala eller fysiska förmågor vara kontraproduktiva, eftersom de korsar en kritisk interpersonell gräns. För avvisande: "Detta beteende är uppenbart och bör vara lätt att förstå." (saknar hänsyn till läsarens potentiella utmaningar) För presumptuous: "Du kommer förmodligen att hitta detta objekt förvirrande, och du borde förmodligen läsa felsökningsguiden när du fastnar." (gör påståenden om läsarens förmågor och erfarenhet) Just Right: "Detta objekt implementerar inte helt gränssnittskontraktet, och kan kasta fel på oväntade sätt. Callers kanske vill använda Bar i stället för en produktion färdig service. Fullständig dokumentation tillhandahålls i README." (Anser begränsningar, erbjuder alternativ, förblir neutral och respektfull). Att hitta en balans mellan hänsyn (att erkänna potentiella utmaningar) och respekt (att undvika antaganden om läsaren) säkerställer att dokumentationen ger stödjande vägledning utan att överskrida interpersonella gränser eller göra antaganden om förmågor. Vägledning: Balansera abstraktion med klarhet Dokumentationen bör använda lämpliga abstraktioner som matchar systemets design, eftersom abstraktion döljer onödiga implementeringsdetaljer och hjälper till att förstå; men berättande och färgglatt språk kan fördunkla sanningen under lager av konceptuell indirektion; därför bör bidragsgivare fokusera på tydliga, direkta beskrivningar av systembeteende. "Foo fungerar som ett transportbälte, den första baren på bältet bearbetas, sedan nästa, och så vidare, tills bältet är tomt, och operatören går till lunch när det inte finns något att göra." Too Imperative: "Foo omsluter varje barobjekt som en nod, var och en med en länk till nästa/föregående nod, och håller en referens till en nod (markerad rotnod), följer sedan återkommande länkarna mellan noderna för att bearbeta dem i den ordning de lades till. Just Right: "Foo bearbetar Bar-objekt med hjälp av en FIFO-rad och är tomma medan raden är tom. Foo använder pub-sub-mönstret för att bearbeta Bar-objekt asynkront." (Clear, direkta beskrivningar med lämplig abstraktion). Att hitta en balans mellan abstraktion (döljer implementeringsdetaljer) och tydlighet (undviker berättande vikt) säkerställer att dokumentationen förklarar implementeringen tydligt utan onödiga begreppsliga indirektioner. Riktlinje: Balansdokumentation Närhet med storlek Dokumentation bör distribueras nära de artefakter som den hänför sig till, eftersom detta förhindrar läsare från att överväldigas av monolitiska dokument och hjälper dem att hitta information lätt; emellertid sprider information över för många dokument förmörkar meningen och lämnar läsarna utan en sammanhängande bild. För centraliserad: Root repository README som innehåller dokumentation för hela repo. (Overwhelming, svårt att navigera) För fragmenterad: En läsning i varje paket med detaljer om det paketet endast, utan översikt eller sammanhang om hur paket relaterar. Just Right: En root README som introducerar repository struktur och filosofi, med mindre granulära READMEs för stora paket. (Balancerad distribution med både översikt och detalj). Att hitta en balans mellan kolokalisering (hålla information nära där det är viktigt) och sammanhållning (tillhandahålla en enhetlig bild) säkerställer att dokumentationen är tillgänglig utan att vara överväldigande eller fragmenterad. Obs!: Att dela upp ett dokument i en katalog i flera filer i samma katalog kan hjälpa när informationen är på rätt plats men dokumentet blir för stort. Utbildning: Lämplig dokumentation Granulär dokumentation (t.ex. Javadoc, inline kommentarer) bör fokusera på den komponent som de hänför sig till, medan dokumentation på hög nivå (t.ex. READMEs, arkitekturdokument) bör fokusera på hur komponenterna integreras och sammansätts tillsammans och hur de passar in i det bredare systemet. Positivt exempel: Javadoc som förklarar en funktions parametrar, returvärde och kantfall. Negativt exempel: Javadoc förklarar hela systemarkitekturen. Positivt exempel: README som förklarar hur paket interagerar och den övergripande designfilosofin. Negativt exempel: README som förklarar den interna implementeringen av varje funktion. Detta säkerställer att läsarna kan hitta lämplig information på lämplig nivå av abstraktion utan redundans eller omfattningsfel. Standard: Amerikansk engelska Amerikansk engelska måste användas, såvida inte domänkonventioner dikterar något annat (t.ex. hänvisning till ett Colours-objekt från ett tredjepartspaket). Positivt exempel: ”Färg” Negativt exempel: ”färg” Detta säkerställer enhetlighet över hela kodbasen och anpassar sig till allmänna mjukvarutekniska konventioner. Undantag: När det underliggande API/system som dokumenteras använder ett annat språk bör dokumentationen matcha. Standard: Korrekt stavning All stavning måste vara korrekt. Positivt exempel: ”Krav” Negativt exempel: ”Krav” Detta upprätthåller professionalism och förhindrar misskommunikation. Standard: Ingen komma efter förkortningar Kommar ska utelämnas efter förkortningar. Ett bra exempel är ”etc”. Negativt exempel: ”etc. ” Detta minskar visuell förvirring. Standard: Ingen Ampersands Ordet "och" måste användas i stället för ampersand-symbolen "&". Positivt exempel: ”Standarder och praxis” Negativt exempel: ”Standarder och praxis” Detta följer formella skrivkonventioner och förbättrar tillgängligheten.
