Tento dokument bol upravený z O knihe Jack Bradshaw . Štýlové smernice Monopoly Efektívna dokumentácia je základným kameňom trvalo udržateľného rozvoja; nevyhnutnosť rastu tímu však sťažuje písanie dokumentácie ako tímu, ktorý nie je roztrieštený a nekonzistentný; preto je potrebná určitá úroveň koordinácie medzi prispievateľmi. Dokonca aj sóloví inžinieri, ktorí kedysi mali voľný priechod, musia teraz bojovať s nekonzistentnosťou dokumentácie generovanej umelou inteligenciou. Môj prvý pokus vyriešiť tento problém vyvrcholil vytvorením všeobecného štandardného dokumentu dokumentácie obsahujúceho 13 predpísaných pravidiel; konkrétne: dokumentácia musí byť neosobná, objektívna, presná, formálna, doslovná, súčasná, zmluvná, terciárna, popisná, definitívna a deklaratívna. Bol to umelecké dielo, bezchybné, vznešené, triumf, ktorý rivaloval len s jeho monumentálnym zlyhaním. Môj zámer bol stanoviť jednoznačné štandardy, ktoré by mohli byť objektívne overené a presadzované AI; avšak problém sa stal zjavným v priebehu času; konkrétne, zatiaľ čo niektoré požiadavky mohli byť objektívne overené (ako napríklad formátovanie zoznamov), iné boli prirodzene subjekt Namiesto opakovania zlomených štandardov bol potrebný zásadný posun v prístupe. Úplne som prepisoval dokument a rozdelil obsah na tri typy: štandardy (absolútne a objektívne), postupy (subjektívne, ale jednoznačné) a usmernenia (vysoko subjektívne a nejednoznačné), s ťažkým posunom smerníc. Zameraním sa na usmernenia na vysokej úrovni namiesto rigidných pravidiel a podporovaním prostredia medzi protichodnými extrémmi, nové smernice poskytujú dostatok priestoru pre individuálny prejav a zároveň odrádzajú známe modely proti vzoru a zlyhania. Príspevok v téme: rozumná múdrosť Repozitórna dokumentácia musí byť objektívna a založená na faktoch, s odkazom na kódovú základňu a v prípade potreby na externé zdroje; subjektívnosť vo forme ťažko získaných skúseností je však neoceniteľná, pretože samotné fakty nemajú užitočný kontext a vyhýbanie sa jedinečným skúsenostiam / perspektívam prispievateľov nevytvára podporné prostredie; dokumentácia by preto mala obsahovať rovnováhu objektívnosti s subjektívnosťou. Too Academic: "FooSort ukazuje O(N log N) priemerný prípad výpočtovej zložitosti, ako formálne dokázal Henderson (1984) prostredníctvom amortizovanej analýzy s využitím potenciálnych funkcií a agregátnych metód. Empirické overenie sa uskutočnilo prostredníctvom simulácie Monte Carlo cez 10 000 rovnomerne rozložených dátových súborov, čo prinieslo 95% interval dôveryhodnosti [0.98N log N, 1.02N log N]. Algoritmická spoľahlivosť bola peer-reviewed a publikovaná v ACM Transactions (DOI:10.1145/12345)." Too Poetic: "FooSort tancuje cez dáta ako pôvabný balet, elegantne tkajúci prvky do ich oprávnených miest. Šepká efektívnosť na každom kroku, symfóniu porovnávaní, ktoré zorganizujú poriadok z chaosu. Rýchlo ako blesk, krásne ako západ slnka, premení vaše neporiadkové zoznamy na nepopierateľné arény čistej harmónie." (Flowery metafory nejasný technický význam) Just Right: „FooSort triedi N položiek v priemernom čase O(N log N), čo ho robí vhodným pre väčšinu prípadov použitia. Avšak, to degraduje na O(N2) na podozrivo zoradených údajov, čo spôsobilo problémy s výrobou v spoločnosti X, keď nahrávanie zákazníkov boli zvyčajne predsortifikované. Z tohto dôvodu, MergeSort je preferovaný pre výrobné pracovné zaťaženie napriek mierne horšie konštantné faktory.“ (Spája objektívne fakty s subjektívnou skúsenosťou a odôvodnený záver). Dosiahnutie rovnováhy medzi objektívnosťou a subjektívnosťou zaisťuje, že dokumentácia zostáva presná a prístupná a zároveň vytvára inkluzívny a podporný priestor pre prispievateľov. Minimalizmus v rovnováhe s dostatočnosťou Prispievatelia musia zahrnúť dostatok informácií, aby sa zabránilo skrytým nákladom chýbajúcej dokumentácie, pretože náklady na ukladanie niekoľkých dodatočných odsekov (kilobajtov) sú oveľa nižšie ako náklady chýbajúceho kontextu (napr. hodiny debugovania, výrobné zlyhania, opätovné vynájdenie kolesa); zbytočné detaily však porazia účel tým, že zakryjú pravdu pod zbytočnými detailmi; preto by dokumentácia mala vynechať zbytočné informácie. Príliš malé: "FooProvider vyrovnáva hodnoty." (Nedostatočný kontext o správaní, uplynutí platnosti alebo známych problémoch) Too Verbose: "FooProvider interne používa ConcurrentHashMap inštanciu s počiatočnou kapacitou 16 a faktorom zaťaženia 0,75 na ukladanie vyrovnávacích hodnôt, ktoré sú samy o sebe zabalené do vlastného objektu CacheEntry obsahujúceho 64-bitový časový razník odvodený od System.nanoTime() pre vysoko presné výpočty uplynutia platnosti a sú vylučiteľné pomocou najmenej nedávno použitej politiky implementovanej prostredníctvom synchronizovaného dvojnásobného zoznamu, ktorý sa prechádza v reverznom poradí počas čistiacich cyklov spúšťaných službou ScheduledExecutorService, ktorá beží na samostatnom drôte daemon. Just Right: "FooProvider vyrovnáva hodnoty s 60-sekundovým TTL pomocou politiky vylúčenia LRU. Vyrovnávacia pamäť beží na pozadí a môže spôsobiť chyby OOM na zariadeniach s obmedzenou pamäťou Android." (Dostatočný kontext o správaní a známych problémoch bez zbytočných podrobností o implementácii). Vytvorenie rovnováhy medzi minimalizmom (vyhýbanie sa zbytočným detailom) a dostatočnosťou (zabezpečenie primeraného kontextu) zaisťuje, že dokumentácia zostane užitočná a prístupná bez toho, aby sa pod nadmernými detailmi implementácie zakryli kritické informácie. Smernica: Vyvážiť minulosť, prítomnosť a budúcnosť Dokumentácia by sa mala vzťahovať na súčasný stav archívu, pretože dokumentovanie budúcnosti riskuje nepresnosť, keď sa zmenia plány, a dokumentovanie minulosti môže zamieňať archív so zastaranými informáciami; historický kontext však často ospravedlňuje súčasnosť, pričom sa chráni pred opakovaním histórie a uznávanie príležitostí pre budúce práce zdôrazňuje známe nedostatky; preto by sa minulosť a budúcnosť mali odkazovať tam, kde je to užitočné. Príliš zamerané na minulosť: „Predchádzajúce implementácie tejto metódy používali štandardnú matematickú knižnicu. Príliš zamerané na budúcnosť: "V štvrťroku plánujeme prepísať analyzátor. Urobíme túto metódu asynchrónnou vo verzii 2.0." (Sľuby bez kontextu o súčasnom stave) Just Right: „Používa sa vlastný analyzátor, pretože štandardný analyzátor knižnice spôsobil regresiu výkonu v verzii 1.2. Táto metóda je synchrónna, ale asynchrónna podpora môže byť pridaná v budúcom vydaní (sledovaná vydaním č. 123).“ (Súčasný stav odôvodnený historickým kontextom a známymi obmedzeniami uznanými s odkazom na sledovanie). Dosiahnutie rovnováhy medzi stabilitou (dokumentovanie toho, čo existuje) a kontextom (poskytovanie potrebného pozadia) zaisťuje, že dokumentácia zostáva presná a užitočná pri zachovaní užitočnej histórie a uznávaní známych obmedzení. Poznámka: Prepojenie budúcich plánov s externými sledovacími odkazmi poskytuje čitateľom spôsob, ako sledovať a získavať aktualizácie. Kľúčové slová: Precíznosť s jednoduchosťou Dokumentácia musí byť technicky presná a presná, pretože nejednoznačné popisy vedú k nedorozumeniam a nesprávnemu používaniu; nadmerné technické detaily však môžu zamaskovať základný koncept a ohromovať čitateľov; preto by mali prispievatelia poskytovať presné vysvetlenia bez zbytočnej zložitosti. Príliš nejasné: "FooProvider robí objekty, keď ich potrebujete." (chýba technická presnosť o správaní) "FooProvider používa mechanizmus inštancializácie továrenského vzoru, v ktorom každé povolanie metódy príslušenstva spúšťa prideľovanie pamäte hromady prostredníctvom nového operátora, čo vedie k vytvoreniu samostatnej inštancie Foo s vlastnou pamäťovou adresou." (Nadmerné technické detaily zakrývajú jednoduché správanie) Just Right: "FooProvider vytvára novú inštanciu Foo na každom hovore." (Presný technický popis bez zbytočnej zložitosti). Dosiahnutie rovnováhy medzi presnosťou (technicky správnou) a jednoduchosťou (rozumiteľnosťou) zaisťuje, že dokumentácia poskytuje presné informácie bez toho, aby ohromila čitateľov podrobnosťami implementácie. Rovnováha medzi formalitou a neformalitou Dokumentácia by mala používať profesionálny jazyk, ktorý zachováva dôveryhodnosť a jasnosť, pretože neformálny slang môže odcudziť čitateľov a znížiť vnímanú autoritu; však nadmerné akademické alebo formálne formulovanie vytvára kognitívne bariéry a vzdialenosť čitateľov; preto by mali prispievatelia používať jasnú, štandardnú technickú angličtinu. Príliš neformálne: "Kotlinov kompilátor je dosť cool a len premení váš kód na bytecode alebo čokoľvek pre rôzne platformy, ako je JVM a veci." (náhodný slang podkopáva dôveryhodnosť) Príliš formálne: "Kotlinov proces kompilácie vyvrcholí generovaním bytekového kódu pre virtuálny stroj Java a analógových artefaktov pre alternatívne substráty vykonávania." (Overly academic phrasing obscures meaning) Just Right: "Kotlin kompiluje do JVM a ďalších platforiem (napr. JS, native)." (Profesionálny tón s jasnou, štandardnou terminológiou). Dosiahnutie rovnováhy medzi formalitou (udržiavanie profesionality) a informalitou (prístupnosť) zaisťuje, že dokumentácia zostáva dôveryhodná a autoritatívna a zároveň je prístupná pre všeobecných inžinierov. Názov: Špecifické referencie Dokumentácia často vyžaduje odkazovanie na ľudí alebo tímy za rozhodnutiami a akciami, pretože priradenie poskytuje zodpovednosť a kontext; Avšak osobné prezývky ("my", "ja", "nás", atď.) sú nejednoznačné; preto by mali prispievatelia používať špecifické názvy jednotlivcov / skupín, kde je to možné. Príliš nejasné: „Dodávateľ FooProvider je odporúčaný.“ (Odporúčaný kým?) Príliš nejasné: „Rozhodli sme sa odstrániť vodičov.“ (Nie je jasné, na koho sa „my“ odkazuje) Just Right: „Kernelový tím sa rozhodol odstrániť ovládače pre výkon v čase spustenia.“ (Špecifické priradenie s jasným odôvodnením). Vytvorenie rovnováhy medzi priradením (poskytovaním zodpovednosti a kontextu) a jasnosťou (vyhnúť sa nejednoznačným pronom) zaisťuje jasnú komunikáciu pomocou špecifických skupinových odkazov (napr. "The Maintainers", "The Compiler Team", "The Security Workgroup") namiesto nejednoznačných pronomien. Výnimka: Pronázvy, ktoré odkazujú na používateľa (napr. „vy“) sú prijateľné (v súvislosti s deklaratívnym a imperatívnym tónom rovnováhy). Rovnováha: deklaratívny a imperatívny tón Dokumentácia by mala opísať obsah úložiska tým, že uvedie jeho správanie a vlastnosti, pretože to udržiava dôraz na artefakty, ktoré obsahuje; postupy, tutoriály a sprievodcovia však môžu byť jasnejšie, keď sú napísané priamo čitateľovi s imperatívnymi pokynmi; preto by mali prispievatelia zhodovať tón s kontextom. Too Imperative: "Musíte nakonfigurovať FooProvider predtým, ako ho použijete. mali by ste najprv zavolať metódu init()." (Komando v referenčnej dokumentácii) Príliš deklaratívne: "Cieľ //foo:bar generuje artefakty pri vykonávaní." (pasívny popis v tutoriáli, kde je potrebné krok za krokom usmernenie) Just Right: "Referenčná dokumentácia: FooProvider musí byť nakonfigurovaný pred použitím volaním init(). Tutorial: Generovať artefakty spustením bazel run //foo:bar." (Declarative tón pre systémové popisy, imperatívny tón pre procedurálne usmernenia). Vytvorenie rovnováhy medzi deklaratívnym (definujúcim systém) a imperatívnym (vodiacim čitateľom) zaisťuje, že dokumentácia poskytuje vhodné informácie pre jeho kontext, pričom referenčná dokumentácia sa zameriava na artefakty a výukové programy poskytujú jasné kroky. Smernica: Vyvážiť dôveru a pokoru Dokumentácia by mala byť napísaná s dôverou, keď je obsah dobre pochopený, pretože zbytočné krytie podkopáva autoritu a vytvára pochybnosti tam, kde by nemala existovať; však, hovoriť s nadmerným presvedčením, keď je pravda neistá, môže odradiť od dôveryhodnosti; preto by mali prispievatelia vyvážiť dôveru s pokorou tým, že uznajú obmedzenia vedomostí a sú transparentní o ich neistote. Príliš váhavé: "FooProvider pravdepodobne nie je bezpečný a existuje malé riziko zlyhania spustenia." (nepotrebné zaistenie o známom správaní) Príliš sebavedomý: "FooProvider bude určite pracovať pod vysokým tlakom pamäte." (falošná istota o netestovanom správaní) Správne: "FooProvider nie je bezpečný. správanie pod vysokým tlakom pamäte je nedefinované a nebolo testované." (Spoľahlivý o známych skutočnostiach, úprimný o neznámych). Vytvorenie rovnováhy medzi dôverou (zriadenie autority) a pokorou (uznanie hraníc) zabezpečuje, že dokumentácia zachováva dôveryhodnosť bez toho, aby vytvárala zbytočné pochybnosti. Príspevok v téme: Rozhodovanie s neutralitou Prispievatelia by mali vykonávať úsudok, aby identifikovali skutočné problémy, obmedzenia a obmedzenia; Avšak, úsudkový jazyk, ktorý útočí na systémy, platformy alebo prispievatelia, je zbytočný; preto by sa prispievatelia mali zamerať na skutkové opisy bez toho, aby sa obviňovali alebo robili rozsiahle negatívne charakterizácie. Príliš neutrálne: „Táto implementácia funguje všade.“ (chýba úsudok, ignoruje skutočné obmedzenia) Príliš rozsudok: "Android je taký špinavý operačný systém, že to nemôže ani spustiť, tiež kto napísal túto sračku?" (osobný útok na platformu a ľudí) Just Right: "Android zariadenia okolo roku 2012 majú obmedzenia pamäte, ktoré bránia tejto implementácii pracovať tak, ako bolo zamýšľané. Dosiahnutie rovnováhy medzi úsudkom (identifikáciou skutočných problémov a obmedzení) a neutralitou (vyhnúť sa osobným útokom a vinám) zaisťuje, že dokumentácia poskytuje presné a užitočné informácie bez toho, aby sa uchýlila k judikatúre. Príspevok v téme: Rovnováha s rešpektom Prispievatelia by mali preukázať úctu k čitateľovi tým, že uznajú potenciálne ťažkosti a ponúkajú podporné usmernenia s vhodným použitím zmierňujúceho jazyka; avšak tvrdenia a predpoklady o duševných alebo fyzických schopnostiach čitateľa môžu byť kontraproduktívne, pretože prekračujú kritickú medziľudskú hranicu; preto by dokumentácia mala ponúkať možnosti a rady, pričom čitateľovi dáva výhodu pochybností a vyhýba sa osobným hodnoteniam. Príliš odmietavé: „Toto správanie je zrejmé a malo by byť ľahko pochopiteľné.“ (Chýba zváženie potenciálnych výziev pre čitateľa) Príliš presvedčivé: "Tento objekt pravdepodobne zistíte zmätený a pravdepodobne by ste si mali prečítať príručku na riešenie problémov, keď sa zaseknete." (Vytvára tvrdenia o schopnostiach a skúsenostiach čitateľa) Just Right: "Tento objekt úplne neimplementuje zmluvu o rozhraní a môže spôsobiť chyby neočakávaným spôsobom. volajúci môžu chcieť použiť Bar namiesto pre službu pripravenú na výrobu. Vytvorenie rovnováhy medzi úvahou (uznaním potenciálnych výziev) a rešpektom (vyhnúť sa predpokladom o čitateľovi) zaisťuje, že dokumentácia poskytuje podporné usmernenia bez prekračovania medziľudských hraníc alebo predpokladov o schopnostiach. Návod: Abstrakcia rovnováhy s jasnosťou Dokumentácia by mala používať vhodné abstrakcie, ktoré zodpovedajú dizajnu systému, pretože abstrakcia skrýva zbytočné detaily implementácie a pomáha pochopiť; naratívny a farebný jazyk však môže zakryť pravdu pod vrstvami koncepčnej nepriamej orientácie; preto by sa mali prispievatelia zamerať na jasné, priame opisy správania systému. Príbeh: "Foo funguje ako dopravný pás, prvý Bar na pás sa spracováva, potom ďalší a tak ďalej, až kým pás nie je prázdny a operátor ide na obed, keď nie je čo robiť." Too Imperative: "Foo obalí každý objekt Bar ako uzol, každý s odkazom na ďalší/predchádzajúci uzol, a drží odkaz na uzol (označený koreňový uzol), potom recursívne sleduje odkazy medzi uzlami, aby ich spracoval v poradí, v akom boli pridané. Just Right: „Foo spracováva objekty Bar pomocou reťazca FIFO a prázdne, zatiaľ čo reťazec je prázdny. Foo používa vzor pub-sub na asynchrónne spracovanie objektov Bar.“ (Clear, priame popisy s vhodnou abstrakciou). Vytvorenie rovnováhy medzi abstrakciou (skrytie detailov implementácie) a jasnosťou (vyhnúť sa naratívnej váhe) zaisťuje, že dokumentácia jasne vysvetľuje implementáciu bez zbytočného koncepčného nepriameho vyjadrenia. Smernica: Blízkosť bilančnej dokumentácie s veľkosťou Dokumentácia by mala byť distribuovaná v blízkosti artefaktov, na ktoré sa vzťahuje, pretože to bráni čitateľom, aby boli premočení monolitickými dokumentmi a pomáha im ľahko nájsť informácie; však šírenie informácií cez príliš veľa dokumentov zamaskuje zmysel a zanecháva čitateľov bez súdržného obrazu; preto by mali prispievatelia vyvážiť kolokáciu s súdržnosťou. Príliš centralizované: koreňové úložisko README obsahujúce dokumentáciu pre celé repo. (preťažujúce, ťažké navigovať) Príliš roztrieštené: Čítať v každom balíku s podrobnosťami len o tomto balíku, bez prehľadu alebo kontextu o tom, ako sa balíky vzťahujú. (chýba súdržnosť) Just Right: Root README, ktorý predstavuje štruktúru a filozofiu archívu, s menšími granulárnymi READMEs pre veľké balíky. (vyvážená distribúcia s prehľadom aj detailom). Vytvorenie rovnováhy medzi kolokáciou (držaním informácií v blízkosti toho, na čom záleží) a súdržnosťou (poskytnutím jednotného obrazu) zabezpečuje, že dokumentácia je prístupná bez toho, aby bola ohromujúca alebo roztrieštená. Poznámka: Rozdelenie dokumentu v adresári do viacerých súborov v tom istom adresári môže pomôcť, keď sú informácie na správnom mieste, ale dokument sa stáva príliš veľký. Praktické: Vhodná dokumentácia rozsahu Granulárna dokumentácia (napr. Javadoc, inline komentáre) by sa mala zamerať na zložku, ku ktorej sa vzťahuje; zatiaľ čo dokumentácia na vysokej úrovni (napr. READMEs, architektonické dokumenty) by sa mala zamerať na to, ako sa komponenty integrujú a skladajú dohromady, a ako sa zmestia do širšieho systému. Pozitívny príklad: Javadoc vysvetľujúci parametre funkcie, hodnoty vrátenia a prípady okrajov. Negatívny príklad: Javadoc vysvetľuje celú systémovú architektúru. Pozitívny príklad: README vysvetľuje, ako balíky interagujú a celkovú filozofiu dizajnu. Negatívny príklad: README vysvetľuje vnútornú implementáciu každej funkcie. To zaisťuje, že čitatelia môžu nájsť vhodné informácie na príslušnej úrovni abstrakcie bez redundancie alebo nesúladu rozsahu. Štandard: americká angličtina Americká angličtina musí byť použitá, pokiaľ doménové konvencie neustanovujú inak (napr. odkazovanie na objekt Colours z balíka tretej strany). Pozitívny príklad: „farba“ Negatívny príklad: „farba“ Tým sa zabezpečí konzistentnosť v celej kódovej báze a zosúladí sa s všeobecnými konvenciami softvérového inžinierstva. Výnimka: Ak dokumentovaný základný API/systém používa iný jazyk, dokumentácia by sa mala zhodovať. Štandard: správne písanie Všetko písanie musí byť správne. Pozitívny príklad: „požiadavky“ Negatívny príklad: „požiadavky“ To udržiava profesionalitu a zabraňuje nesprávnej komunikácii. Štandard: bez kommy po skratkách Komíny sa musia po skratkách vynechať. Pozitívny príklad: „etc“ Negatívny príklad: „etc.“ Tým sa znižuje vizuálny neporiadok. Štandard: Žiadne obmedzenia Slovo "a" musí byť použité namiesto ampersand symbol "&". Pozitívny príklad: „Normy a postupy“ Negatívny príklad: „Standardy a postupy“ To dodržiava formálne písomné konvencie a zlepšuje prístupnosť.
