Ovaj dokument je prilagođen od Sljedeći članakJack Bradshaw . Smjernice o stilu Monorepo Učinkovita dokumentacija je kamen temeljac održivog razvoja; međutim, neizbježnost rasta tima otežava pisanje dokumentacije kao tima koja nije rascjepkana i nedosljedna; stoga je potreban određeni stupanj koordinacije između doprinosnika. čak i solo inženjeri, koji su nekada imali slobodan prolaz, sada se moraju boriti s nedosljednošću dokumentacije generirane AI-om. Moj prvi pokušaj rješavanja ovog problema kulminirao je stvaranjem općeg dokumentacijskog standarda koji sadrži 13 propisnih pravila; posebno: dokumentacija mora biti neosobna, objektivna, točna, formalna, doslovna, trenutna, ugovorna, teresa, opisna, konačna i deklarativna. To je bilo umjetničko djelo, besprijekorno, sublimno, trijumf koji se natječe samo s njegovim monumentalnim neuspjehom. Moja je namjera bila uspostaviti nedvosmislene standarde koji bi mogli biti objektivno provjereni i provjereni od strane AI-a; međutim, problem je postao očigledan tijekom vremena; posebno, dok su neki zahtjevi mogli biti objektivno provjereni (kao što je oblikovanje popisa), drugi su bili inherentno subjektivni (zanimljivost, Umjesto da ponavljam razbijene standarde, potrebna je temeljna promjena u pristupu. Potpuno sam prepisala dokument i podijelila sadržaj na tri vrste: standarde (apsolutno i objektivno), prakse (subjektivno, ali nedvosmisleno) i smjernice (izuzetno subjektivno i nedvosmisleno), s teškim preokretom prema smjernicama. Usredotočivši se na smjernice na visokoj razini umjesto na rigidna pravila, te potičući sredinu između suprotstavljenih krajnosti, nove direktive pružaju dovoljno prostora za individualno izražavanje, dok odvraćaju poznate načine protiv uzoraka i neuspjeha. Naslov: Razumna mudrost Dokumentacija repozitorija mora biti objektivna i utemeljena na činjenicama, s upućivanjem na bazu kodova i vanjske izvore gdje je to primjereno; međutim, subjektivnost u obliku teško stečenog iskustva je neprocjenjiva, jer činjenice same nemaju kontekst da bi bile korisne, a izbjegavanje jedinstvenih iskustava/perspektiva doprinositelja ne stvara podržavajuće okruženje; stoga, dokumentacija treba sadržavati ravnotežu objektivnosti i subjektivnosti. Too Academic: "FooSort prikazuje O(N log N) prosječne računalne složenosti slučajeva, kao što je službeno dokazao Henderson (1984) putem amortizirane analize koristeći potencijalne funkcije i agregirane metode. empirijska validacija je provedena kroz Monte Carlo simulaciju preko 10.000 jednako raspodijeljenih skupova podataka, što rezultira 95% intervala pouzdanosti [0.98N log N, 1.02N log N]. Algoritamsko dosljednost je pregledana i objavljena u ACM Transactions (DOI:10.1145/12345)." Too Poetic: "FooSort pleše kroz podatke poput gracioznog baleta, elegantno tkajući elemente na svoja pravedna mjesta. Šapće učinkovitost na svakom krugu, simfonija usporedbi orkestrirajući red iz kaosa. Brzo kao munja, lijepo kao zalazak sunca, pretvara vaše neredne liste u nepristine arene čiste harmonije." (Flowery metafore nejasno tehničko značenje) Jednostavno ispravno: "FooSort sortira N stavke u O(N log N) prosječnom vremenu, što ga čini prikladnim za većinu slučajeva uporabe. međutim, degradiše na O(N2) na prijavljenim sortiranim podacima, što je uzrokovalo probleme s proizvodnjom u tvrtki X kada su upisi klijenata obično unaprijed sortirani. Uspostavljanje ravnoteže između objektivnosti i subjektivnosti osigurava da dokumentacija ostane točna i dostupna, a istodobno stvara uključivi i podržavajući prostor za doprinositelje. Smjernica: Ravnoteža minimalizma s dovoljnošću Sudionici moraju uključiti dovoljno informacija kako bi se izbjegli skriveni troškovi manjkajuće dokumentacije, jer je trošak skladištenja nekoliko dodatnih stavaka (kilobajta) daleko niži od troškova manjkajućeg konteksta (npr. sati debugiranja, neuspjeha u proizvodnji, ponovnog izuma kotača); međutim, nepotrebni detalji pobjeđuju svrhu tako što zatvaraju istinu pod nepotrebnim detaljima; stoga bi dokumentacija trebala izostaviti nepotrebne informacije. Previše minimalno: "FooProvider cache vrijednosti." (Nedovoljni kontekst o ponašanju, isteku ili poznatim problemima) Too Verbose: "FooProvider interno koristi ConcurrentHashMap instantiated s početnim kapacitetom od 16 i faktorom opterećenja od 0,75 za pohranu cached vrijednosti, koje su same obložene u prilagođen CacheEntry objekt koji sadrži 64-bitni vremenski žig koji proizlazi iz System.nanoTime() za visoko precizne istek izračuna, i su evicable koristeći najmanje nedavno korištena politika implementiran preko sinhroniziranog dvostruko povezanog popisa koji je prošao u obrnutom redoslijedu tijekom čišćenja ciklusa pokrenut od strane ScheduledExecutorService koji radi na odvojenom daemon thread. Samo ispravno: "FooProvider cache vrijednosti s 60-sekundnim TTL-om koristeći politiku uklanjanja LRU. Cache radi na pozadini niti i može uzrokovati OOM pogreške na Android uređajima s ograničenim pamćenjem." (Dovoljno kontekst o ponašanju i poznatim problemima bez nepotrebnih detalja implementacije). Uspostavljanje ravnoteže između minimalizma (izbjegavanje nepotrebnih detalja) i adekvatnosti (pružanje adekvatnog konteksta) osigurava da dokumentacija ostane korisna i dostupna bez zatajivanja kritičnih informacija pod prekomjernim detaljima provedbe. Smjernica: Ravnoteža prošlosti, sadašnjosti i budućnosti Dokumentacija bi se trebala odnositi na sadašnje stanje repozitorija, jer dokumentiranje budućnosti predstavlja rizik od netočnosti kada se planovi mijenjaju, a dokumentiranje prošlosti može zamotati repozitorij zastarjelim informacijama; međutim, povijesni kontekst često opravdava sadašnjost, dok se čuva od ponavljanja povijesti, a priznavanje mogućnosti za buduće radove naglašava poznate nedostatke; stoga bi prošlost i budućnost trebali biti upućeni gdje je korisno. Previše usmjeren na prošlost: "Prošle implementacije ove metode koristile su standardnu matematičku knjižnicu. Previše usmjeren na budućnost: "U četvrtom tromjesečju planiramo ponovno napisati analizator. učinit ćemo ovu metodu asincrono u verziji 2.0." (Obećanja bez konteksta o trenutnom stanju) Just Right: "Prikupljeni analizator se koristi jer je standardni analizator knjižnice uzrokovao regresije performansi u verziji v1.2. Ova metoda je sinhronska, ali asynchronous podrška može biti dodana u budućem izdanju (tracked by issue #123)." (Sadašnje stanje opravdano povijesnim kontekstom i poznatim ograničenjima priznatim s referencama za praćenje). Uspostavljanje ravnoteže između stabilnosti (dokumentiranja onoga što postoji) i konteksta (pružanje potrebne pozadine) osigurava da dokumentacija ostane točna i korisna, uz očuvanje korisne povijesti i prepoznavanje poznatih ograničenja. Napomena: Povezivanje budućih planova s vanjskim referencama za praćenje daje čitateljima način praćenja i dobivanja ažuriranja. Smjernica: Ravnoteža preciznosti s jednostavnošću Dokumentacija mora biti tehnički točna i precizna, jer nejasni opisi dovode do pogrešnog razumijevanja i pogrešne uporabe; međutim, prekomjerni tehnički detalji mogu zasjeniti osnovni koncept i preplaviti čitatelje; stoga bi doprinositelji trebali pružiti točna objašnjenja bez nepotrebne složenosti. Previše nejasno: "FooProvider stvara objekte kada vam trebaju." (nedostaje tehnička preciznost o ponašanju) Također detaljno: "FooProvider koristi mehanizam za instantiranje tvornice u kojem svaka invokacija pristupačne metode izaziva raspodjelu pamćenja preko novog operatora, što rezultira izgradnjom zasebne instance Foo s vlastitom adresom memorije." (Prekomjerni tehnički detalji zatvaraju jednostavno ponašanje) Samo ispravno: "FooProvider stvara novu instanci Foo na svakom pozivu." (Točan tehnički opis bez nepotrebne složenosti). Postizanje ravnoteže između preciznosti (biti tehnički ispravan) i jednostavnosti (biti razumljiv) osigurava da dokumentacija prenosi točne informacije bez preuveličavanja čitatelja s provedbenim detaljima. Smjernica: Ravnoteža formalnosti s neformalnošću Dokumentacija bi trebala koristiti profesionalni jezik koji održava vjerodostojnost i jasnoću, jer neformalni sleng može oduševiti čitatelje i smanjiti percipirani autoritet; međutim, prekomjerno akademsko ili formalno izražavanje stvara kognitivne barijere i udaljava čitatelje; stoga bi doprinositelji trebali koristiti jasan, standardni tehnički engleski. Previše neformalno: "Kotlinov kompilator je prilično cool i samo pretvara vaš kod u bajtecode ili bilo što za različite platforme poput JVM-a i stvari." Too Formal: "Kotlinov proces kompilacije kulminira u stvaranju bajtokoda za Java Virtual Machine i analognih artefakata za alternativne podloge za izvršenje." Just Right: "Kotlin kompilira na JVM i druge platforme (npr. JS, native)." (Profesionalni ton s jasnom, standardnom terminologijom). Postizanje ravnoteže između formalnosti (očuvanje profesionalnosti) i neformalnosti (biti pristupačan) osigurava da dokumentacija ostaje vjerodostojna i autoritativna, dok je dostupna općim inženjerima. Smjernice: Reference za posebne skupine Dokumentacija često zahtijeva upućivanje na ljude ili timove iza odluka i akcija, jer pripisivanje pruža odgovornost i kontekst; međutim, osobni nadimci ("mi", "ja", "mi", itd.) su dvosmisleni; stoga, doprinositelji trebaju koristiti specifična imena pojedinaca / skupina gdje je to moguće. Previše nejasno: "Preporučuje se FooProvider." (Preporučuje tko?) Too Vague: "Odlučili smo ukloniti vozače." (Nije jasno na koga se "mi" odnosimo) Samo ispravno: "Kernel tim odlučio ukloniti vozače za performanse u radnom vremenu." (posebna atribucija s jasnim obrazloženjem). Uspostavljanje ravnoteže između pripisivanja (pružanje odgovornosti i konteksta) i jasnoće (izbjegavanje dvosmislenih pronomena) osigurava jasnu komunikaciju koristeći specifične reference grupe (npr. "The Maintainers", "The Compiler Team", "The Security Workgroup") umjesto nejasnih pronomena. Iznimka: Pronomi koji se odnose na korisnika (npr. „vi“) su prihvatljivi (povezani sa Balance Declarative i Imperative Tone). Ključna riječ: deklaracijski i imperativni ton Dokumentacija bi trebala opisati sadržaj repozitorija navodeći njegova ponašanja i svojstva, jer to zadržava fokus na artefakte koje sadrži; međutim, postupci, tutoriali i vodiči mogu biti jasniji kada su napisani izravno čitatelju s imperativnim uputama; stoga, doprinosi trebaju odgovarati tonu kontekstu. Too Imperative: "Morate konfigurirati FooProvider prije nego što ga koristite. Too Declarative: "Cilj //foo:bar generira artefakte kada se izvrši." (Pasivni opis u vodiču gdje je potrebno korak po korak usmjeravanje) Just Right: "Referencijska dokumentacija: FooProvider mora biti konfiguriran prije korištenja pozivanjem init(). Tutorial: Generirajte artefakte pokretanjem bazel run //foo:bar." (Deklaracijski ton za opis sustava, imperativni ton za postupovne smjernice). Uspostavljanje ravnoteže između deklarativnog (definirajući sustav) i imperativnog (vodi čitatelja) osigurava da dokumentacija pruža odgovarajuće informacije za svoj kontekst, dok se referentna dokumentacija usredotočuje na artefakte i tutoriale koji pružaju jasne korake koji se mogu poduzeti. Smjernica: Ravnoteža povjerenja i poniznosti Dokumentacija bi trebala biti napisana s povjerenjem kada je sadržaj dobro shvaćen, jer nepotrebno zaštitno osiguranje potkopava autoritet i stvara sumnju gdje ne bi trebalo postojati; međutim, govoriti s prekomjernim uvjerenjem kada je istina neizvjesna može odvratiti vjerodostojnost; stoga bi doprinositelji trebali uravnotežiti povjerenje s poniznošću priznavanjem ograničenja znanja i transparentnošću o njihovoj neizvjesnosti. Previše oklijevajuće: "FooProvider vjerojatno nije siguran i postoji mali rizik od neuspjeha u radnom vremenu." (nepotrebno osiguravanje o poznatom ponašanju) Previše samouvjeren: "FooProvider će definitivno raditi pod visokim pritiskom memorije." (Lažna sigurnost o neprovjerenom ponašanju) Jednostavno ispravno: "FooProvider nije bezopasno. ponašanje pod visokim pritiskom memorije nije definirano i nije testirano." (Sigurno o poznatim činjenicama, iskreno o nepoznatim). Uspostavljanje ravnoteže između povjerenja (otvaranje ovlasti) i poniznosti (priznavanje granica) osigurava da dokumentacija održava vjerodostojnost bez stvaranja nepotrebnih sumnji. Smjernica: Ravnoteža presude s neutralnošću Sudionici bi trebali provoditi procjenu kako bi identificirali stvarna pitanja, ograničenja i ograničenja; međutim, jezik procjene koji napada sustave, platforme ili sudionike je beskoristan; stoga, sudionici bi se trebali usredotočiti na opise činjenica bez pripisivanja krivnje ili čineći opsežne negativne karakterizacije. Previše neutralno: "Ova implementacija djeluje svugdje." (nedostaje sudbina, ignorira stvarna ograničenja) Too Judgmental: "Android je takav prljavi operativni sustav da to ne može ni pokrenuti, također tko je napisao ovo sranje?" (osobni napad na platformu i ljude) Just Right: "Android uređaji oko 2012. imaju ograničenja memorije koja sprečavaju ovu implementaciju da radi kako je predviđeno. Uspostavljanje ravnoteže između prosudbe (identificiranje stvarnih pitanja i ograničenja) i neutralnosti (izbjegavanje osobnih napada i krivnje) osigurava dokumentaciju koja pruža točne i korisne informacije bez pribjegavanja procjenjivanju. Smjernica: Razmatranje ravnoteže s poštovanjem Sudionici bi trebali pokazati razmatranje za čitatelja priznavanjem potencijalnih poteškoća i pružanjem potpornih smjernica, uz primjereno korištenje omekšavajućeg jezika; međutim, tvrdnje i pretpostavke o čitateljevim mentalnim ili tjelesnim sposobnostima mogu biti kontraproduktivne, jer prelaze kritičnu međuljudsku granicu; stoga bi dokumentacija trebala ponuditi opcije i savjete, dok čitatelju daje korist od sumnje i izbjegava osobne procjene. Too Dismissive: "Ovo ponašanje je očito i trebalo bi biti lako razumjeti." (Nema razmatranja za potencijalne izazove čitatelja) Previše pretpostavka: "Vjerojatno ćete naći ovaj objekt zbunjujuće, a vjerojatno biste trebali pročitati vodič za rješavanje problema kada ste zaglavljeni." (Iznosi tvrdnje o sposobnostima i iskustvu čitatelja) Samo ispravno: "Ovaj objekt ne provodi u potpunosti ugovor o sučeljavanju, i može baciti pogreške na neočekivane načine. Pozivači mogu željeti koristiti Bar umjesto za proizvodnju spremne usluge. potpuna dokumentacija se pruža u README." (priznaje ograničenja, nudi opcije, ostaje neutralna i poštivajući). Uspostavljanje ravnoteže između razmatranja (priznavanja potencijalnih izazova) i poštovanja (izbjegavanje pretpostavki o čitatelju) osigurava dokumentaciju koja pruža potporne smjernice bez prekoračenja međuljudskih granica ili pretpostavki o sposobnostima. Smjernica: Ravnoteža abstrakcije s jasnoćom Dokumentacija bi trebala koristiti odgovarajuće abstrakcije koje odgovaraju dizajnu sustava, jer abstrakcija skriva nepotrebne detalje implementacije i pomaže u razumijevanju; međutim, narativni i šareni jezik mogu zasjeniti istinu pod slojevima konceptualne neizravnosti; stoga bi se doprinositelji trebali usredotočiti na jasne, izravne opise ponašanja sustava. "Foo radi kao konvejerski pojas, prvi bar na pojasu se obrađuje, zatim sljedeći, i tako dalje, sve dok pojas nije prazan, a operater ide na ručak kada nema što učiniti." (Metafora zatvara značenje) Too Imperative: "Foo zagrljava svaki Bar objekt kao čvor, svaki s vezom na sljedeći / prethodni čvor, i drži referenciju na čvor (označen korijenski čvor), a zatim recursivno slijedi veze između čvorova kako bi ih obrađivao u redoslijedu u kojem su dodani. Just Right: "Foo obrađuje Bar objekte koristeći FIFO red i idle dok je red prazan. Foo koristi pub-sub uzorak za asincrono obrađivanje Bar objekata." (Clear, izravni opisi s odgovarajućom abstrakcijom). Uspostavljanje ravnoteže između abstrakcije (skrivanje detalja implementacije) i jasnoće (izbjegavanje narativne težine) osigurava dokumentaciju koja jasno objašnjava implementaciju bez nepotrebne konceptualne neizravnosti. Smjernica: Bliskost dokumentacije ravnoteže s veličinom Dokumentacija bi trebala biti raspodijeljena u blizini artefakata na koje se odnosi, jer to sprečava čitatelje da budu preplavljeni monolitnim dokumentima i pomaže im da lako pronađu informacije; međutim, širenje informacija preko previše dokumenata zamračuje značenje i ostavlja čitatelje bez kohezivne slike; stoga, doprinosnici trebaju uravnotežiti kolokaciju s kohezijom. Previše centraliziran: korijenski repozitorij README koji sadrži dokumentaciju za cijeli repo. Previše fragmentirano: Čitanje u svakom paketu s detaljima samo tog paketa, bez pregleda ili konteksta o tome kako se paketi odnose. Just Right: Root README koji uvodi strukturu i filozofiju skladišta, s manjim granularnim READMEs za velike pakete. (Uravnotežena distribucija s pregledom i detaljem). Uspostavljanje ravnoteže između kolokacije (državanje informacija blizu onoga što je važno) i koheziji (pružanje jedinstvene slike) osigurava da dokumentacija bude dostupna bez pretjerivanja ili fragmentacije. Napomena: Podjeljivanje dokumenta u direktoriju na više datoteka u istom direktoriju može pomoći kada su informacije na pravom mjestu, ali dokument postaje prevelik. Praksa: odgovarajuća dokumentacija opseg Granularna dokumentacija (npr. Javadoc, inline komentari) trebala bi se usredotočiti na komponentu s kojom se odnose; dok bi dokumentacija na visokoj razini (npr. READMEs, arhitektonski dokumenti) trebala biti usmjerena na to kako komponente integriraju i sastave zajedno i kako se uklapaju u širi sustav. Pozitivan primjer: Javadoc koji objašnjava parametre funkcije, povratnu vrijednost i slučajeve rubova. Negativni primjer: Javadoc objašnjava cijelu arhitekturu sustava. Pozitivan primjer: README objašnjavajući kako paketi međusobno djeluju i ukupnu filozofiju dizajna. Negativni primjer: README objašnjava unutarnju implementaciju svake funkcije. To osigurava da čitatelji mogu pronaći odgovarajuće informacije na odgovarajućoj razini abstrakcije bez redundancije ili neusklađenosti opsega. Standard: Američki engleski Američki engleski jezik mora se koristiti, osim ako konvencije o domenama propisuju drukčije (npr. upućivanje na objekt Colours iz paketa treće strane). Pozitivan primjer: “boja” Negativni primjer: “boja” To osigurava dosljednost u cijeloj bazi kodova i usklađuje se s općim konvencijama softverskog inženjeringa. Iznimka: Kada se osnovni API/sustav koji se dokumentira koristi drugi jezik, dokumentacija bi trebala odgovarati. Ključna riječ: ispravno pisanje Svako pismo mora biti ispravno. Pozitivan primjer: „Zahtjevi“ Negativni primjer: „Zahtjevi“ To održava profesionalnost i sprječava pogrešne komunikacije. Standard: bez komama nakon skraćenica Komme se moraju izostaviti nakon skraćivanja. Dobar primjer je „etc“. Negativni primjer: “etc.” To smanjuje vizualnu zamućenost. Standard: nema ampersandova Riječ "i" mora se koristiti umjesto ampersand simbola "&". Pozitivan primjer: „Standardi i prakse“ Negativni primjer: "Standardi i prakse" To se pridržava formalnih konvencija pisanja i poboljšava pristupačnost.
