Ky dokument është përshtatur nga Për Jack Bradshaw . Direktivat e stilit Monedha Dokumentacioni efektiv është guri themelor i zhvillimit të qëndrueshëm; megjithatë, pashmangshmëria e rritjes së ekipit e bën të vështirë të shkruash dokumentacion si ekip që nuk është i fragmentuar dhe i paqëndrueshëm; prandaj, një shkallë e koordinimit midis kontribuesve është e nevojshme. madje edhe inxhinierët solo, të cilët dikur kishin një kalim të lirë, tani duhet të luftojnë me papajtueshmërinë e dokumentacionit të gjeneruar nga AI. unë vetë përdor AI për të gjeneruar disa nga dokumentacioni në arkivin tim, por me kalimin e kohës janë bërë të pakënaqur me rezultatet; në mënyrë specifike, mungesa e konsistencës dhe koherencës në të gjithë bazën e kodit. Përpjekja ime e parë për të zgjidhur këtë problem kulmoi në krijimin e një Dokumenti Standard të Dokumentacionit të Përgjithshëm që përmban 13 rregulla prescriptive; në mënyrë specifike: Dokumentacioni duhet të jetë i papërshtatshëm, objektiv, i saktë, formal, letrar, aktual, kontraktual, i përkohshëm, përshkrues, përfundimtar dhe deklarativ. Ishte një vepër arti, i papërshtatshëm, sublime, një triumf që konkurronte vetëm me dështimin e tij monumental. Qëllimi im ishte të krijonte standarde të paqarta që mund të verifikoheshin objektivisht dhe të zbatoheshin nga AI; megjithatë, një problem u bë i dukshëm me kalimin e kohës; në mënyrë specifike, ndërsa disa kërkesa mund të verifikoheshin objektivisht (si form Në vend që të përsërisja standardet e thyera, ishte e nevojshme një ndryshim themelor në qasje. Unë rishkruaja plotësisht dokumentin dhe ndan përmbajtjen në tre lloje: standarde (absolute dhe objektive), praktika (subjektive por të paqarta) dhe udhëzime (shumë subjektive dhe të paqarta), me një ndryshim të rëndë drejt udhëzimeve. Duke u fokusuar në udhëzime të nivelit të lartë në vend të rregullave të ngurta, dhe duke inkurajuar një terren të mesëm midis ekstremeve të kundërta, direktivat e reja ofrojnë hapësirë të madhe për shprehje individuale, ndërsa pengojnë mënyrat e njohura anti-pattern dhe dështimi. Kjo krijon një hapësirë gjithëpërfshirëse ku kontribuesit mund të flasin Fjalë kyçe: urtësi e arsyeshme Dokumentacioni i depozitës duhet të jetë objektiv dhe i bazuar në fakte, me referenca në bazën e kodit dhe burime të jashtme, kur është e përshtatshme; megjithatë, subjektiviteti në formën e përvojës së fituar me vështirësi është i çmuar, pasi faktet vetëm nuk kanë kontekstin për të qenë të dobishme, dhe shmangia e përvojave / perspektivave unike të kontribuesve nuk krijon një mjedis mbështetës; prandaj, dokumentacioni duhet të përmbajë një ekuilibër të objektivitetit me subjektivitetin. Too Academic: "FooSort ekspozon kompleksitetin llogaritës mesatar të rastit O(N log N), siç dëshmohet zyrtarisht nga Henderson (1984) përmes analizës së amortizuar duke përdorur funksionet e mundshme dhe metodat e grumbulluara. validimi empirik është kryer përmes simulimit Monte Carlo në 10,000 grupe të dhënash të shpërndara në mënyrë uniforme, duke dhënë një interval besimi 95% të [0.98N log N, 1.02N log N]. Too Poetic: "FooSort vallëzon përmes të dhënave si një balet i mrekullueshëm, duke tërhequr me elegancë elementet në vendet e tyre të ligjshme. Ajo pëshpërit efikasitetin në çdo kthesë, një simfoninë e krahasimeve që orkestrojnë rendin nga kaosi. Shpejt si rrufeja, e bukur si perëndimi i diellit, ajo shndërron listat tuaja të çrregullta në grumbullime të papërshkruara të harmonisë së pastër." (Flowery metaphors obscure technical meaning) Just Right: "FooSort rendit N artikuj në O(N log N) kohë mesatare, duke e bërë atë të përshtatshme për shumicën e rasteve të përdorimit. megjithatë, ajo degradohet në O(N2) në të dhënat e renditura në mënyrë të raportuar, gjë që shkaktoi probleme të prodhimit në Kompania X kur ngarkimet e klientëve zakonisht ishin të para-renditura. Balancimi midis objektivitetit dhe subjektivitetit siguron që dokumentacioni të mbetet i saktë dhe i arritshëm, duke krijuar një hapësirë gjithëpërfshirëse dhe mbështetëse për kontribuesit. Udhëzim: Balancimi i minimalizmit me mjaftueshmërinë Kontribuesit duhet të përfshijnë informacion të mjaftueshëm për të shmangur kostot e fshehura të dokumentacionit të munguar, pasi kostoja e ruajtjes së disa paragrafëve shtesë (kilobajt) është shumë më e ulët se kostoja e kontekstit të munguar (p.sh. orë debugging, dështime të prodhimit, rishikimi i rrotës); megjithatë, detajet e panevojshme mposhtin qëllimin duke fshehur të vërtetën nën detajet e panevojshme; prandaj, dokumentacioni duhet të përjashtojë informacionin e panevojshëm. Too Minimale: "FooProvider cache values." (Kontekst i pamjaftueshëm për sjelljen, skadimin ose problemet e njohura) Too Verbose: "FooProvider përdor në mënyrë të brendshme një ConcurrentHashMap instantiated me një kapacitet fillestar prej 16 dhe një faktor ngarkesës prej 0.75 për të ruajtur vlerat e cache, të cilat vetë janë të mbështjellë në një objekt të përshtatur CacheEntry që përmban një timestamp 64-bit të rrjedhur nga System.nanoTime() për llogaritje me saktësi të lartë të skadimit, dhe janë të shmangshme duke përdorur një politikë më pak të përdorur kohët e fundit të zbatuar nëpërmjet një liste të sinkronizuar të dyfishtë-lidhur që kalon në mënyrë të kundërt gjatë cikleve të pastrimit të shkaktuara nga një shërbim ScheduledExecutorService që punon në një fije të veçantë daemon. Just Right: "FooProvider cache vlerat me një TTL 60-sekondëshe duke përdorur një politikë të përjashtimit LRU. Cache shkon në një fije sfond dhe mund të shkaktojë gabime OOM në pajisjet Android me kujtesë të kufizuar." (Kontekst i mjaftueshëm për sjelljen dhe problemet e njohura pa detaje të panevojshme të zbatimit). Marrja e një ekuilibri midis minimalizmit (duke shmangur detajet e panevojshme) dhe mjaftueshmërisë (duke siguruar kontekstin e duhur) siguron që dokumentacioni të mbetet i dobishëm dhe i arritshëm pa fshehur informacionet kritike nën detajet e tepërta të zbatimit. Udhëzim: Balancimi i së kaluarës, të tashmes dhe të ardhmes Dokumentacioni duhet të lidhet me gjendjen e tanishme të arkivorit, pasi dokumentimi i së ardhmes rrezikon pasaktësi si planet ndryshojnë, dhe dokumentimi i së kaluarës mund të ngatërrojë arkivorin me informacione të vjetëruara; megjithatë, konteksti historik shpesh justifikon të tashmen ndërsa ruan kundër përsëritjes së historisë, dhe pranimi i mundësive për veprat e ardhshme thekson mangësitë e njohura; prandaj, e kaluara dhe e ardhmja duhet të referohen kur është e dobishme. Too Past-Focused: "Zbatimet e kaluara të kësaj metode përdorën bibliotekën standarde matematikore.Ka pasur probleme me analizuesin, por ato janë rregulluar." (Detajet e parëndësishme pa kontekstin e veprimit) Too Future-Focused: "Në Q4 ne planifikojmë të rishkruajmë analizuesin.Ne do ta bëjmë këtë metodë asynchronous në v2.0." ( premtime pa kontekst për gjendjen aktuale) Just Right: "Një analizues i përshtatur përdoret sepse analizuesi standard i bibliotekës shkaktoi regresione të performancës në v1.2.Kjo metodë është e sinkronizuar, por mbështetja asinkron mund të shtohet në një lëshim të ardhshëm (të ndjekur nga numri #123)." (Shteti i tanishëm i justifikuar nga konteksti historik dhe kufizimet e njohura të njohura me referencën e ndjekjes). Marrja e një ekuilibri midis stabilitetit (dokumentimi i asaj që ekziston) dhe kontekstit (duke siguruar sfondin e nevojshëm) siguron që dokumentacioni të mbetet i saktë dhe i dobishëm duke ruajtur historinë e dobishme dhe duke pranuar kufizimet e njohura. Shënim: Lidhja e planeve të ardhshme me referencat e gjurmimit të jashtëm u jep lexuesve një mënyrë për të ndjekur dhe për të marrë përditësime. Udhëzim: Balancimi i saktësisë me thjeshtësinë Dokumentacioni duhet të jetë teknikisht i saktë dhe i saktë, pasi përshkrimet e paqarta çojnë në keqkuptime dhe përdorim të gabuar; megjithatë, detajet e tepërta teknike mund të errësojnë konceptin kryesor dhe të mbushin lexuesit; prandaj, kontribuesit duhet të japin shpjegime të sakta pa kompleksitet të panevojshëm. Too Vague: "FooProvider bën objekte kur ju keni nevojë për to." (Mungon saktësi teknike në lidhje me sjelljen) Too Detailed: "FooProvider përdor një mekanizëm të instantizimit të modelit të fabrikës ku çdo thirrje e metodës së aksesorit shkakton shpërndarjen e kujtesës së grumbulluar përmes operatorit të ri, duke rezultuar në ndërtimin e një instance të veçantë Foo me adresën e vet të kujtesës." (Detajet e tepërta teknike fshehin sjelljen e thjeshtë) Just Right: "FooProvider krijon një instancë të re të Foo në çdo thirrje." (përshkrim teknik i saktë pa kompleksitet të panevojshëm). Marrja e një ekuilibri midis saktësisë (duke qenë teknikisht e saktë) dhe thjeshtësisë (duke qenë e kuptueshme) siguron që dokumentacioni transmeton informacion të saktë pa mbingarkuar lexuesit me detajet e zbatimit. Udhëzues: Balancimi i formalitetit me informalitetin Dokumentacioni duhet të përdorë gjuhë profesionale që ruan besueshmërinë dhe qartësinë, pasi slangu informal mund të huazojë lexuesit dhe të zvogëlojë autoritetin e perceptuar; megjithatë, fraza e tepërt akademike ose formale krijon pengesa njohëse dhe distancon lexuesit; prandaj, kontribuesit duhet të përdorin anglisht të qartë, standard teknik. Too Informal: "Kompilatori i Kotlin është mjaft i ftohtë dhe thjesht e kthen kodin tuaj në bytecode ose çfarëdo për platforma të ndryshme si JVM dhe gjëra." (slang i rastësishëm minon besueshmërinë) Too Formal: "Procesi i kompilimit të Kotlin kulminon në gjenerimin e bytecode për Java Virtual Machine dhe artefakte të ngjashme për substratet alternative të ekzekutimeve." Just Right: "Kotlin kompilon në JVM dhe platforma të tjera (p.sh. JS, native)." (Ton profesional me terminologji të qartë, standarde). Marrja e një ekuilibri midis formalitetit (mbajtja e profesionalizmit) dhe informalitetit (që është i arritshëm) siguron që dokumentacioni të mbetet i besueshëm dhe autoritar ndërsa është i arritshëm për inxhinierët e përgjithshëm. Udhëzim: Referencat specifike të grupit Dokumentacioni shpesh kërkon referencimin e njerëzve ose ekipeve prapa vendimeve dhe veprimeve, pasi atribuimi siguron përgjegjësi dhe kontekst; megjithatë, prononcat personale ("ne", "unë", "ne", etj.) janë të paqarta; prandaj, kontribuesit duhet të përdorin emra të veçantë individual / grup ku është e mundur. Shumë e paqartë: "The FooProvider është e rekomanduar." (Rekomanduar nga kush?) Too Vague: "Ne kemi vendosur të heqim shoferët." (nuk është e qartë se kush "ne" i referohet) Just Right: "Ekipi i Kernelit vendosi të heqë shoferët për performancën e kohës së drejtimit." (atributi specifik me arsyetim të qartë). Marrja e një ekuilibri midis atribuimit (duke siguruar përgjegjësinë dhe kontekstin) dhe qartësisë (duke shmangur prononcat e paqarta) siguron komunikim të qartë duke përdorur referenca specifike të grupit (p.sh. "The Maintainers", "The Compiler Team", "The Security Workgroup") në vend të prononca të paqarta. Përjashtim: Pronët që i referohen përdoruesit (p.sh. "ju") janë të pranueshme (në lidhje me Balance Declarative dhe Imperative Tone). Rregullorja e balancës: Tone deklarative dhe imperative Dokumentacioni duhet të përshkruajë përmbajtjen e depozitës duke deklaruar sjelljet dhe vetitë e saj, pasi kjo mban fokusin në artefaktet që përmban; megjithatë, procedurat, tutorialet dhe udhëzimet mund të jenë më të qarta kur shkruhen direkt lexuesit me udhëzime imperative; prandaj, kontribuesit duhet të përputhen me tonin e kontekstit. Too Imperative: "Ju duhet të konfiguroni FooProvider para se ta përdorni atë. Too Declarative: "Objektivi //foo:bar gjeneron artefakte kur ekzekutohet." (shkrimi pasiv në një tutorial ku nevojitet udhëzimi hap pas hapi) Just Right: "Dokumentacioni i referencës: FooProvider duhet të konfigurohet para përdorimit duke thirrur init(). Tutorial: Krijoni artefakte duke drejtuar bazel run //foo:bar." (Toni deklarativ për përshkrimet e sistemit, ton imperativ për udhëzime procedurale). Marrja e një ekuilibri midis deklarative (që përcakton sistemin) dhe imperative (që udhëzon lexuesin) siguron që dokumentacioni ofron informacion të përshtatshëm për kontekstin e tij, me dokumentacion referencë që fokusohet në artefakte dhe tutoriale që ofrojnë hapa të qartë të veprimit. Udhëzues: Bilanci i besimit dhe përulësisë Dokumentacioni duhet të shkruhet me besim kur përmbajtja është e kuptuar mirë, pasi hedhja e panevojshme minon autoritetin dhe krijon dyshime ku nuk duhet të ekzistojë; megjithatë, duke folur me bindje të tepruar kur e vërteta është e pasigurt mund të shtrembërojë besueshmërinë; prandaj, kontribuesit duhet të balancojnë besimin me përulësinë duke pranuar kufizimet e njohurive dhe duke qenë transparent në lidhje me pasigurinë e tyre. Shumë i heshtur: "FooProvider ndoshta nuk është i sigurt dhe ka një rrezik të vogël të dështimit të kohës së drejtimit." (Hidhje e panevojshme rreth sjelljes së njohur) Shumë i sigurt: "FooProvider patjetër do të punojë nën presion të lartë të kujtesës." (Siguria e rreme për sjelljen e pashqyrtuar) Vetëm të drejtë: "FooProvider nuk është thread-safe. sjellja nën presion të lartë të kujtesës është e papërcaktuar dhe nuk është testuar." (Besnik në lidhje me faktet e njohura, i sinqertë në lidhje me të panjohurat). Marrja e një ekuilibri midis besimit (që krijon autoritet) dhe përulësisë (që pranon kufijtë) siguron që dokumentacioni ruan besueshmërinë pa krijuar dyshime të panevojshme. Udhëzues: Gjyqi i balancuar me neutralitetin Kontribuesit duhet të ushtrojnë gjykim për të identifikuar çështjet e vërteta, kufizimet dhe kufizimet; megjithatë, gjuha e gjykimit që sulmon sistemet, platformat ose kontribuesit është e padobishme; prandaj, kontribuesit duhet të përqëndrohen në përshkrimet faktike pa vënë fajin ose duke bërë karakterizime të thella negative. Too Neutral: "Kjo zbatim funksionon kudo" (Mungon gjykimi, injoron kufizimet reale) Too Judgmental: "Android është një sistem operativ i tillë i ndyrë që nuk mund ta drejtojë as këtë, gjithashtu kush e shkroi këtë ndyrë?" (sulm personal në platformë dhe njerëz) Just Right: "Android pajisjet rreth 2012 kanë kufizime të kujtesës që pengojnë këtë zbatim të punojë siç është planifikuar. zbatimi Foo nuk punon në Android." (gjyqi i shëndoshë me përshkrime specifike, informative dhe faktike). Marrja e një ekuilibri midis gjykimit (identifikimi i çështjeve dhe kufizimeve reale) dhe neutralitetit (shmangia e sulmeve personale dhe fajësimit) siguron që dokumentacioni të sigurojë informacion të saktë dhe të dobishëm pa iu drejtuar gjykimit. Udhëzim: Vlerësimi i ekuilibrit me respekt Kontribuesit duhet të tregojnë konsideratë për lexuesin duke njohur vështirësitë e mundshme dhe duke ofruar udhëzime mbështetëse, me gjuhën e butë të përdorur në mënyrë të përshtatshme; megjithatë, pretendimet dhe supozimet për aftësitë mendore ose fizike të lexuesit mund të jenë kundërproduktive, pasi kalojnë një kufi kritik ndërpersonal; prandaj, dokumentacioni duhet të ofrojë opsione dhe këshilla, duke i dhënë lexuesit përfitimin e dyshimit dhe duke shmangur vlerësimet personale. Too Dismissive: "Kjo sjellje është e qartë dhe duhet të jetë e lehtë për t'u kuptuar." (Mungon konsiderata për sfidat e mundshme të lexuesit) Shumë presumptuous: "Ju ndoshta do të gjeni këtë objekt konfuz, dhe ju ndoshta duhet të lexoni udhëzuesin e zgjidhjes së problemeve kur ju të bllokuar." (Të bëjë pretendime në lidhje me aftësitë dhe përvojën e lexuesit) Just Right: "Ky objekt nuk zbaton plotësisht kontratën e ndërfaqes, dhe mund të hedhë gabime në mënyra të papritura. thirrësit mund të dëshirojnë të përdorin Bar në vend të një shërbimi të gatshëm të prodhimit. Dokumentacioni i plotë është dhënë në README." (Përcakton kufizimet, ofron opsione, mbetet neutral dhe respektiv). Marrja e një ekuilibri midis shqyrtimit (njohja e sfidave të mundshme) dhe respekti (shmangia e supozimeve rreth lexuesit) siguron që dokumentacioni ofron udhëzime mbështetëse pa kaluar kufijtë ndërpersonale ose duke bërë supozime për aftësitë. Udhëzues: Abstraksioni i ekuilibrit me qartësinë Dokumentacioni duhet të përdorë abstraksione të përshtatshme që përputhen me dizajnin e sistemit, pasi abstraksioni fsheh detajet e panevojshme të zbatimit dhe ndihmon në kuptimin; megjithatë, gjuha narrative dhe e gjallë mund të errësojë të vërtetën nën shtresat e indirektimit konceptual; prandaj, kontribuesit duhet të përqëndrohen në përshkrime të qarta, të drejtpërdrejta të sjelljes së sistemit. Too Narrative: "Foo punon si një rrip transportues, Bar i parë në rrip është përpunuar, pastaj tjetër, dhe kështu me radhë, derisa rrip është bosh, dhe operatori shkon për drekë kur nuk ka asgjë për të bërë." Too Imperative: "Foo mbështjell çdo objekt Bar si një nod, secili me një lidhje me nodin e ardhshëm / të mëparshëm, dhe mban një referencë për një nod (node rrënjë të shënuar), pastaj ndjek në mënyrë recursive lidhjet midis nodeve për t'i përpunuar ato në rendin që u shtuan. Just Right: "Foo përpunon objektet Bar duke përdorur një radhë FIFO, dhe hesht ndërsa radhët janë bosh. Foo përdor modelin pub-sub për të përpunuar objektet Bar në mënyrë asinkron." (Clear, përshkrime të drejtpërdrejta me abstraksionin e duhur). Marrja e një ekuilibri midis abstraksionit (fshehja e detajeve të zbatimit) dhe qartësisë (shmangia e peshës narrative) siguron që dokumentacioni shpjegon zbatimin në mënyrë të qartë pa indirekte të panevojshme konceptuale. Udhëzimi: Dokumentacioni i bilancit i afërt me madhësinë Dokumentacioni duhet të shpërndahet afër artefakteve me të cilat lidhet, pasi kjo parandalon lexuesit nga të mbytur nga dokumentet monolitike dhe i ndihmon ata të gjejnë informacionin lehtë; megjithatë, përhapja e informacionit në shumë dokumente errëson kuptimin dhe i lë lexuesit pa një imazh koheziv; prandaj, kontribuesit duhet të balancojnë kolokalizimin me kohezionin. Shumë i centralizuar: Repozitori i rrënjëve README që përmban dokumentacion për të gjithë repo. (Përmbytje, e vështirë për të lundruar) Too Fragmented: Një README në çdo paketë me detajet e atij paketi vetëm, pa ndonjë përmbledhje ose kontekst se si lidhen paketat. (Mungon kohezioni) Just Right: Një README rrënjë që paraqet strukturën dhe filozofinë e depozitave, me READMEs më të vogla granulare për paketat e mëdha. (shpërndarja e balancuar me të dy përmbledhjet dhe detajet). Marrja e një ekuilibri midis kolokalizimit (mbajtja e informacionit afër ku ka rëndësi) dhe kohezionit (duke siguruar një imazh të unifikuar) siguron që dokumentacioni të jetë i arritshëm pa qenë mbizotërues ose i fragmentuar. Shënim: Ndarja e një dokumenti në një direktori në skedarë të shumtë në të njëjtin direktori mund të ndihmojë kur informacioni është në vendin e duhur, por dokumenti është duke u bërë shumë i madh. Praktikë: Dokumentacioni i përshtatshëm për fushën Dokumentacioni granular (p.sh. Javadoc, komente në linjë) duhet të përqëndrohet në komponentin me të cilin lidhet; ndërsa dokumentacioni i nivelit të lartë (p.sh. READMEs, dokumente arkitekturore) duhet të përqëndrohet në mënyrën se si komponentët integrohen dhe përbëjnë së bashku, dhe se si ato përshtaten në sistemin më të gjerë. Shembull pozitiv: Javadoc shpjegon parametrat e një funksioni, vlerën e kthimit dhe rastet e skajeve. Shembull negativ: Javadoc shpjegon të gjithë arkitekturën e sistemit. Shembull pozitiv: README duke shpjeguar se si ndërveprojnë paketat dhe filozofinë e përgjithshme të projektimit. Shembull negativ: README duke shpjeguar zbatimin e brendshëm të çdo funksioni. Kjo siguron që lexuesit mund të gjejnë informacionin e duhur në nivelin e duhur të abstraksionit pa redundancë ose mosmarrëveshje të fushës. Standard: Anglishtja Amerikane Anglishtja amerikane duhet të përdoret, përveçse kur konvencionet e domain-it diktojnë ndryshe (p.sh. referencimi i një objekti Colours nga një paketë e palës së tretë). Shembull pozitiv: “ngjyra” Shembull negativ: “ngjyra” Kjo siguron qëndrueshmëri në të gjithë bazën e kodit dhe përputhet me konvencionet e përgjithshme të inxhinierisë së softuerit. Përjashtim: Kur API / sistemi bazë që dokumentohet përdor një gjuhë tjetër, atëherë dokumentacioni duhet të përputhet. Fjalë kyçe: spelling correct Të gjitha shkronjat duhet të jenë të sakta. Shembull pozitiv: “kërkesat” Shembull negativ: “kërkesat” Kjo ruan profesionalizmin dhe parandalon keqkomunikimin. Standard: No Comma pas shkurtimeve Komamat duhet të hiqen pas shkurtimeve. Një shembull pozitiv: “etc.” Shembull negativ: «etc. » Kjo zvogëlon shqetësimin vizual. Standard: Asnjë Ampersands Fjala "dhe" duhet të përdoret në vend të simbolit ampersand "&". Shembull pozitiv: "Standardet dhe praktikat" Shembull negativ: "Standardet dhe praktikat" Kjo i përmbahet konventave formale të shkrimit dhe përmirëson aksesueshmërinë.
