Šis dokuments ir pielāgots no Džeka Bradshava dzīve . Stila direktīvas Monopols Efektīva dokumentācija ir ilgtspējīgas attīstības stūrakmens; tomēr komandas izaugsmes neizbēgamība apgrūtina dokumentācijas rakstīšanu kā komandu, kas nav sadrumstalota un nesaskaņota; tāpēc ir nepieciešama zināma koordinācijas pakāpe starp dalībniekiem. Mans pirmais mēģinājums atrisināt šo problēmu kulminēja vispārējā dokumentācijas standarta dokumenta izveidē, kurā bija 13 noteikumu noteikumi; konkrēti: dokumentācijai jābūt bezpersoniskai, objektīvai, precīzai, formālai, burtiskai, pašreizējai, līgumiskai, terzētiskai, aprakstošai, galīgajai un deklaratīvai. Tas bija mākslas darbs, bez kļūdām, augstsirdīgs, triumfs, kas konkurēja tikai ar tās monumentālo neveiksmi. Mans nodoms bija izveidot viennozīmīgus standartus, kurus var objektīvi pārbaudīt un īstenot AI; tomēr laika gaitā kļuva acīmredzama problēma; konkrēti, kamēr dažas prasības varēja objektīvi pārbaudīt (piemēram, saraksta formāšana), citi bija dabiski Tā vietā, lai atkārtotu pārkāptos standartus, bija nepieciešama fundamentāla pieeja. Es pilnībā pārrakstīju dokumentu un sadalīju saturu trijos veidos: standarti (absolūti un objektīvi), prakse (subjektīva, bet viennozīmīga) un vadlīnijas (ļoti subjektīvi un neskaidri), ar smagu novirzi virzienā uz vadlīnijām. Koncentrējoties uz augsta līmeņa vadlīnijām, nevis stingriem noteikumiem, un veicinot viduslaiku starp pretējām galējībām, jaunās direktīvas nodrošina lielu telpu individuālai izteiksmei, vienlaikus atturot no zināmiem pretpasākumiem un neveiksmju veidiem. Pamatnostādne: saprātīga gudrība Repozitorijas dokumentācijai jābūt objektīvai un uz faktiem balstītai, attiecīgā gadījumā atsaucoties uz kodu bāzi un ārējiem avotiem; tomēr subjektivitāte grūti nopelnītas pieredzes veidā ir nenovērtējama, jo faktiem vien trūkst lietderīga konteksta, un izvairīšanās no ieguldītāju unikālajām pieredzēm/perspektīvām nerada atbalstošu vidi; tādēļ dokumentācijai būtu jāietver līdzsvars starp objektivitāti un subjektivitāti. Too Academic: "FooSort demonstrē O(N log N) vidējo gadījumu aprēķinu sarežģītību, kā to oficiāli pierādīja Henderson (1984) ar amortizētas analīzes palīdzību, izmantojot potenciālās funkcijas un apkopošanas metodes. empīriskā validācija tika veikta, izmantojot Monte Carlo simulāciju 10 000 vienveidīgi sadalīto datu kopumu, radot 95% uzticamības intervālu [0.98N log N, 1.02N log N]. Algoritmiskā pareizība ir recenzēta un publicēta ACM Transactions (DOI:10.1145/12345)." Too Poetic: "FooSort dejo caur datiem kā graciozs balets, eleganti tvaicējot elementus savās tiesiskajās vietās. Tas šūpojas par efektivitāti katrā virzienā, salīdzinājumu simfonija, kas orķestrē kārtību no haosa. Ātrs kā zibens, skaists kā saulriets, tas pārvērš jūsu neskaidros sarakstus par tīru harmoniju." (Flowery metaforas neskaidra tehniska nozīme) Just Right: "FooSort šķir N priekšmetus vidējā laikā O(N log N), kas padara to piemērotu lielākajai daļai lietošanas gadījumu. Tomēr tas samazinās līdz O(N2) par ziņotās šķirošanas datiem, kas izraisīja ražošanas problēmas uzņēmumā X, kad klientu augšupielādes parasti tika iepriekš šķirotas. Līdzsvars starp objektivitāti un subjektīvumu nodrošina, ka dokumentācija paliek precīza un pieejama, vienlaikus radot iekļaujošu un atbalstošu telpu ieguldītājiem. Minimālisma līdzsvars ar pietiekamību Dalībniekiem ir jāiekļauj pietiekami daudz informācijas, lai izvairītos no dokumentācijas trūkuma slēptajām izmaksām, jo dažu papildu punktu (kilobītu) uzglabāšanas izmaksas ir daudz zemākas nekā trūkstošā konteksta izmaksas (piemēram, debugēšanas stundas, ražošanas neveiksmes, riteņa atkārtota izgudrošana); tomēr nevajadzīgas detaļas pārspēj mērķi, aptverot patiesību ar nevajadzīgām detaļām; tādēļ dokumentācijai vajadzētu izlaist nevajadzīgu informāciju. Pārāk minimāls: "FooProvider kešatmiņas vērtības." (nepietiekams konteksts par uzvedību, termiņa beigām vai zināmiem jautājumiem) Too Verbose: "FooProvider iekšēji izmanto ConcurrentHashMap instantiated ar sākotnējo jaudu 16 un slodzes koeficientu 0,75 uzglabāt cached vērtības, kas paši ir iesaiņoti pielāgotu CacheEntry objektu, kas satur 64-bitu laika zīmogu, kas iegūts no System.nanoTime() augstas precizitātes derīguma termiņa aprēķiniem, un ir evicable, izmantojot vismazāk nesen izmantoto politiku, kas īstenota, izmantojot sinhronizētu dubultsaistītu sarakstu, kas tiek šķērsota apgrieztā secībā tīrīšanas ciklu laikā, ko izraisa ScheduledExecutorService, kas darbojas uz atsevišķu daemon stieņa. piezīme: Tas parasti neizdodas Android ierīcēm OOM kļ Just Right: "FooProvider kešatmiņā saglabā vērtības ar 60 sekunžu TTL, izmantojot LRU izslēgšanas politiku. kešatmiņa darbojas uz fona un var izraisīt OOM kļūdas Android ierīcēs ar atmiņas ierobežojumiem." (pietiekams konteksts par uzvedību un zināmajām problēmām bez nevajadzīgām īstenošanas detaļām). Līdzsvars starp minimālismu (izvairīšanos no nevajadzīgām detaļām) un pietiekamību (nodrošinot atbilstošu kontekstu) nodrošina, ka dokumentācija paliek noderīga un pieejama, neslēpjot kritisko informāciju pārmērīgas īstenošanas detaļās. Vadlīnijas: līdzsvars pagātnē, tagadnē un nākotnē Dokumentācijai vajadzētu būt saistītai ar repozitorijas pašreizējo stāvokli, jo, dokumentējot nākotni, plānu maiņa var radīt neprecizitātes, un pagātnes dokumentēšana var apgrūtināt repozitoriju ar novecojušu informāciju; tomēr vēsturiskais konteksts bieži vien attaisno pašreizējo, vienlaikus sargājot vēsturi no atkārtošanās, un, atzīstot iespējas nākotnes darbiem, izceļas zināmi trūkumi; tāpēc pagātne un nākotne būtu jāatsaucas, ja tas ir noderīgi. Pārāk pagātnes orientēts: "Pēdējās šīs metodes īstenošanas izmantoja standarta matemātikas bibliotēku. Pārāk orientēts uz nākotni: "4. ceturksnī mēs plānojam pārrakstīt analīzi. mēs padarīsim šo metodi asimetrisku versijā 2.0." (Pārliecības bez konteksta par pašreizējo stāvokli) Just Right: "Personalizēts analizators tiek izmantots tāpēc, ka standarta bibliotēkas analizators izraisīja veiktspējas regresijas versijā v1.2. Šī metode ir sinhrona, bet nākotnē var tikt pievienots asimetrisks atbalsts (izlaidums #123)." (Pašreizējais stāvoklis ir pamatots ar vēsturisko kontekstu un zināmiem ierobežojumiem, kas atzīti ar izsekošanas atsauci). Līdzsvars starp stabilitāti (dokumentējot to, kas pastāv) un kontekstu (nodrošinot nepieciešamo fonu) nodrošina, ka dokumentācija paliek precīza un noderīga, vienlaikus saglabājot noderīgu vēsturi un atzīstot zināmos ierobežojumus. Piezīme.: Saistot nākotnes plānus ar ārējām izsekošanas atsaucēm, lasītāji var sekot līdzi un saņemt atjauninājumus. Ieteikums: līdzsvarot precizitāti ar vienkāršību Dokumentācijai jābūt tehniski precīzai un precīzai, jo neskaidri apraksti noved pie pārpratumiem un nepareizas lietošanas; tomēr pārmērīgas tehniskās detaļas var aptumšot pamatkoncepciju un apgrūtināt lasītājus; tādēļ sniedzējiem būtu jāsniedz precīzi paskaidrojumi bez nevajadzīgas sarežģītības. Pārāk neskaidrs: "FooProvider rada objektus, kad jums tie ir nepieciešami." (trūkst tehniskas precizitātes par uzvedību) Pārāk Detalizēts: "FooProvider izmanto rūpnīcas modeļa instantiācijas mehānismu, kurā katra piederības metodes atsaukšana izraisa kaudzes atmiņas piešķiršanu, izmantojot jaunu operatoru, kā rezultātā tiek izveidota atšķirīga Foo instance ar savu atmiņas adresi." (Pārmērīgas tehniskās detaļas aptver vienkāršu uzvedību) Just Right: "FooProvider izveido jaunu Foo instanci katrā zvanā." (precīzs tehniskais apraksts bez nevajadzīgas sarežģītības). Līdzsvars starp precizitāti (būt tehniski pareizam) un vienkāršību (būt saprotamam) nodrošina, ka dokumentācija sniedz precīzu informāciju, nepārspiežot lasītājus ar īstenošanas minutiae. Pamatnostādne: Formalitātes līdzsvars ar neformalitāti Dokumentācijai jāizmanto profesionāla valoda, kas saglabā ticamību un skaidrību, jo neformālais slengs var novirzīt lasītājus un samazināt uztveramo autoritāti; tomēr pārmērīga akadēmiska vai formāla frāze rada kognitīvus šķēršļus un attālinās lasītājus; tādēļ ieguldītājiem vajadzētu izmantot skaidru, standarta tehnisko angļu valodu. Pārāk neformāls: "Kotlin kompilators ir diezgan foršs un tikai pārvērš jūsu kodu burtu kodā vai kaut ko citu dažādām platformām, piemēram, JVM un lietām." Pārāk formāls: "Kotlin kompilācijas process kulminē bytecodes ģenerēšanā Java virtuālajai mašīnai un analogo artefaktu radīšanā alternatīviem izpildes substrātiem." Just Right: "Kotlin kompilē uz JVM un citām platformām (piemēram, JS, native)." (Profesionāls tonis ar skaidru, standarta terminoloģiju). Līdzsvars starp formalitāti (uzturot profesionalitāti) un neformalitāti (būt pieejamam) nodrošina, ka dokumentācija paliek uzticama un autoritāra, vienlaikus kļūstot pieejama vispārējiem inženieriem. Pamatnostādnes: Konkrētas grupas atsauces Dokumentācija bieži prasa atsaukties uz cilvēkiem vai komandām, kas atrodas aiz lēmumiem un darbībām, jo piešķiršana nodrošina pārskatatbildību un kontekstu; tomēr personīgie uzvārdi ("mēs", "es", "mēs", utt.) ir neskaidri; tādēļ ieguldītājiem vajadzētu izmantot konkrētus indivīda / grupas vārdus, ja iespējams. Pārāk neskaidrs: "FooProvider ir ieteicams." (Kam ieteicams?) Pārāk neskaidrs: "Mēs nolēmām noņemt autovadītājus." (nav skaidrs, uz ko attiecas "mēs") Just Right: "Kernela komanda nolēma noņemt vadītājus darbalaika veiktspējas dēļ." (Specifisks atribūts ar skaidru pamatojumu). Līdzsvars starp piešķiršanu (nodrošinot atbildību un kontekstu) un skaidrību (izvairoties no neskaidriem pronomiem) nodrošina skaidru saziņu, izmantojot konkrētas grupas atsauces (piemēram, "The Maintainers", "The Compiler Team", "The Security Workgroup") nevis neskaidrus pronomus. Izņēmums: Pronomi, kas attiecas uz lietotāju (piemēram, "jūs") ir pieņemami (attiecas uz Balance Declarative un Imperative Tone). Balansēšanas deklaratīvais un imperatīvais tonis Dokumentācijai vajadzētu aprakstīt repozitorijas saturu, norādot tās uzvedību un īpašības, jo tas saglabā uzmanību uz tā esošajiem artefaktiem; tomēr procedūras, apmācības un rokasgrāmatas var būt skaidrākas, ja tās rakstītas tieši lasītājam ar imperatīviem norādījumiem; tādēļ ieguldītājiem jāatbilst toni kontekstam. Too Imperative: "Jums ir jākonfigurē FooProvider, pirms to izmantojat. Too Declarative: " //foo:bar mērķis rada artefaktus, kad tas tiek izpildīts." (Pasīvs apraksts apmācībā, kur nepieciešama soli pa solim vadība) Just Right: "References dokumentācija: FooProvider ir jākonfigurē pirms lietošanas, izsaucot init(). Līdzsvars starp deklaratīvo (definējot sistēmu) un imperatīvo (vadot lasītāju) nodrošina, ka dokumentācija sniedz atbilstošu informāciju par tās kontekstu, ar atsauces dokumentāciju, kas koncentrējas uz artefaktiem un apmācībām, kas nodrošina skaidrus rīcības soļus. Pamatnostādne: līdzsvars starp uzticību un pazemību Dokumentācija būtu jāraksta ar pārliecību, kad saturs ir labi saprotams, jo nevajadzīga apdrošināšana apdraud autoritāti un rada šaubas, ja tās nevajadzētu pastāvēt; tomēr, runājot ar pārmērīgu pārliecību, kad patiesība ir nenoteikta, var atturēt no uzticamības; tādēļ ieguldītājiem vajadzētu līdzsvarot uzticību ar pazemību, atzīstot zināšanu ierobežojumus un būt pārredzamam par to nenoteiktību. Pārāk neskaidrs: "FooProvider, iespējams, nav drošs un pastāv neliels runtime neveiksmes risks." (nepieciešama apdrošināšana par zināmu uzvedību) Pārāk pārliecināts: "FooProvider noteikti darbosies zem augsta atmiņas spiediena." (nepareiza pārliecība par nepārbaudītu uzvedību) Just Right: "FooProvider nav bezjēdzīgi. uzvedība zem augsta atmiņas spiediena ir nedefinēta un nav pārbaudīta." (Uzticīgs par zināmiem faktiem, godīgs par nezināmiem). Līdzsvars starp uzticību (autoritātes noteikšanu) un pazemību (limitu atzīšanu) nodrošina, ka dokumentācija saglabā uzticamību, neradot nevajadzīgas šaubas. Pamatnostādne: līdzsvarot spriedumu ar neitralitāti Dalībniekiem vajadzētu izmantot spriedumu, lai identificētu reālas problēmas, ierobežojumus un ierobežojumus; tomēr spriedumu valoda, kas uzbrūk sistēmām, platformām vai dalītājiem, ir bezjēdzīga; tādēļ dalītājiem vajadzētu koncentrēties uz faktu aprakstiem, neuzliekot vainu vai veicot visaptverošas negatīvas raksturošanas. Pārāk neitrāls: "Šī īstenošana darbojas visur." (trūkst sprieduma, ignorē reālos ierobežojumus) Pārāk spriedums: "Android ir tik netīra operētājsistēma, ka tā pat nevar to palaist, arī kas rakstīja šo muļķi?" (personas uzbrukums platformai un cilvēkiem) Just Right: "Android ierīcēm aptuveni 2012. gadā ir atmiņas ierobežojumi, kas neļauj šai īstenošanai darboties kā paredzēts. Līdzsvars starp spriedumu (atpazīstot reālos jautājumus un ierobežojumus) un neitralitāti (novēršot personīgos uzbrukumus un vainu) nodrošina, ka dokumentācija sniedz precīzu un noderīgu informāciju, neizmantojot spriedumu. Pamatnostādne: līdzsvars ar cieņu Dalībniekiem būtu jāparāda uzmanība lasītājam, atzīstot iespējamās grūtības un piedāvājot atbalstošas vadlīnijas, ar piemērotu mīkstinošu valodu; tomēr apgalvojumi un pieņēmumi par lasītāja garīgajām vai fiziskajām spējām var būt kontrproduktīvi, jo tie šķērso kritisku starppersonu robežu; tādēļ dokumentācijai būtu jāpiedāvā iespējas un padomi, vienlaikus dodot lasītājam priekšrocības no šaubām un izvairoties no personīgajiem vērtējumiem. Pārāk noraidošs: "Šī uzvedība ir acīmredzama un tai vajadzētu būt viegli saprotamai." (trūkst uzmanības lasītāja iespējamajiem izaicinājumiem) Pārāk aizdomīgs: "Jūs, iespējams, atradīsiet šo objektu neskaidru, un jums, iespējams, vajadzētu izlasīt problēmu novēršanas rokasgrāmatu, kad esat iestrēdzis." (Izdara apgalvojumus par lasītāja spējām un pieredzi) Just Right: "Šis objekts pilnībā neīsteno saskarnes līgumu un var izraisīt kļūdas negaidītos veidos. zvanītāji var vēlēties izmantot Bar, nevis ražošanas gatavu pakalpojumu. Līdzsvars starp apsvērumu (potenciālo izaicinājumu atzīšanu) un cieņu (izvairīšanos no pieņēmumiem par lasītāju) nodrošina, ka dokumentācija sniedz atbalstošas vadlīnijas, nepārkāpjot starppersonu robežas vai pieņemot pieņēmumus par spējām. Ieteikums: Abstrakcijas līdzsvarošana ar skaidrību Dokumentācijā jāizmanto atbilstošas abstrakcijas, kas atbilst sistēmas dizainam, jo abstrakcija slēpj nevajadzīgas īstenošanas detaļas un palīdz izprast; tomēr stāstījuma un krāsaina valoda var aptumšot patiesību zem konceptuālās netiešības slāņiem; tādēļ ieguldītājiem jākoncentrējas uz skaidriem, tiešiem sistēmas uzvedības aprakstiem. Too Narrative: "Foo darbojas kā konveijera jostasvieta, pirmā Bāra uz jostasvietas tiek apstrādāta, tad nākamā un tā tālāk, līdz jostasvieta ir tukša, un operators dodas uz pusdienām, kad nav ko darīt." Too Imperative: "Foo iesaiņo katru Bar objektu kā mezglu, katrs ar saiti uz nākamo / iepriekšējo mezglu, un tur atsauci uz mezglu (marķēts sakņu mezglu), tad recursīvi seko saites starp mezgliem, lai tos apstrādātu tādā secībā, kādā tie tika pievienoti. Just Right: "Foo apstrādā bāru objektus, izmantojot FIFO rindas, un paliek tukši, kamēr rindas ir tukšas. Līdzsvars starp abstrakciju (noslēpjot īstenošanas detaļas) un skaidrību (izvairoties no stāstījuma svara) nodrošina, ka dokumentācija skaidri izskaidro īstenošanu bez nevajadzīgas konceptuālas netiešas norādes. Pamatnostādne: bilances dokumentācijas tuvināšana ar izmēru Dokumentācija jāizplata tuvu artifaktiem, uz kuriem tā attiecas, jo tas novērš lasītāju pārņemšanu ar monolītiskiem dokumentiem un palīdz viņiem viegli atrast informāciju; tomēr informācijas izplatīšana pārāk daudzos dokumentos aptumšo nozīmi un atstāj lasītājus bez kohēzijas attēla; tādēļ sniedzējiem vajadzētu līdzsvarot kolokāciju ar kohēziju. Pārāk centralizēts: sakņu repozitorijs README, kas satur dokumentāciju par visu repo. (pārslogot, grūti navigēt) Pārāk sadrumstalota: katrā paketē ir lasījums ar detaļām tikai par šo paketi, bez pārskata vai konteksta par to, kā paketes attiecas. (trūkst kohēzijas) Just Right: Root README, kas iepazīstina ar repozitoriju struktūru un filozofiju, ar mazākiem granulāriem READMEs lieliem pakāpieniem. (Sabalansēts sadalījums ar kopsavilkumu un detaļām). Līdzsvars starp kolokāciju (informācijas saglabāšanu tuvu tam, kur tā ir svarīga) un kohēziju (nodrošinot vienotu attēlu) nodrošina, ka dokumentācija ir pieejama bez pārspīlējuma vai sadrumstalotības. Piezīme.: Dokumentu sadalīšana direktorijā vairākos failos tajā pašā direktorijā var palīdzēt, ja informācija ir pareizajā vietā, bet dokuments kļūst pārāk liels. Prakse: piemērota dokumentācija Granulārai dokumentācijai (piemēram, Javadoc, inline komentāriem) jākoncentrējas uz komponentu, uz kuru tā attiecas, bet augsta līmeņa dokumentācijai (piemēram, READMEs, arhitektūras dokumentiem) jākoncentrējas uz to, kā komponenti apvienojas un veido kopā, un kā tie iekļaujas plašākā sistēmā. Pozitīvs piemērs: Javadoc, kas izskaidro funkcijas parametrus, atgriezenisko vērtību un malas gadījumus. Negatīvs piemērs: Javadoc, kas izskaidro visu sistēmas arhitektūru. Pozitīvs piemērs: README izskaidrojot, kā paketes mijiedarbojas un vispārējo dizaina filozofiju. Negatīvs piemērs: README, kas izskaidro katras funkcijas iekšējo īstenošanu. Tas nodrošina, ka lasītāji var atrast atbilstošu informāciju atbilstošā abstrakcijas līmenī bez redundances vai darbības jomas neatbilstības. Standarts: amerikāņu angļu Ir jāizmanto amerikāņu angļu valoda, izņemot gadījumus, kad domēna konvencijas nosaka citādi (piemēram, atsaucoties uz Colours objektu no trešās puses paketes). Pozitīvs piemērs: “krāsa” Negatīvs piemērs: “krāsa” Tas nodrošina konsekvenci visā koda bāzē un atbilst vispārējām programmatūras inženierijas konvencijām. Izņēmums: Ja dokumentētā pamatā esošā API/sistēma izmanto citu valodu, tad dokumentācijai jāatbilst. Standarts: pareiza rakstzīme Visiem rakstiem jābūt pareiziem. Pozitīvs piemērs: “prasības” Negatīvs piemērs: “pieprasījumi” Tas saglabā profesionalitāti un novērš nepareizu saziņu. Standarts: bez komas pēc saīsinājumiem Komas ir jāizslēdz pēc saīsinājumiem. Labs piemērs ir “etc”. Negatīvs piemērs: “etc.” Tas samazina vizuālo satricinājumu. Standarts: nav ampersands Vārds “un” jāizmanto ampersand simbolu “&” vietā. Pozitīvs piemērs: “Standarti un prakse” Negatīvs piemērs: “Standarti un prakse” Tas ievēro oficiālās rakstīšanas konvencijas un uzlabo pieejamību.
