Ieguvumi:
- Spēja izveidot README, docstring un izmaiņu žurnālu melnrakstus, pamatojoties uz mērķauditoriju un avotu, izmantojot AI
- Spēja dokumentācijā atdalīt slāņus “kas/kā” un “kāpēc” un pievienot “kāpēc” kā cilvēkam
- Instalēšanas darbību pārbaude, personīgi palaižot tās un padarot dokumentu par daļu no koda maiņas
Visbiežāk novārtā atstātā, bet visilgāk izmantotā programmatūras daļa ir dokumentācija. Kods ir lasāms pat pēc mēnešiem; Cilvēks, kurš to uzrakstījis, ir prom, konteksts ir aizmirsts, un paliek tikai tas, kas tika uzrakstīts. Labs README (ievaddokuments, kas izskaidro, kas ir projekts un kā to instalēt un palaist), skaidrojošie koda komentāri un jaunākā API dokumentācija (atsauce, kas izskaidro saskarnes lietošanu) tieši nosaka komandas ātrumu. AI noņem lielu daļu no dokumentācijas “rakstīšanas noguruma”, taču tai ir slazds: mākslīgais intelekts no koda var secināt, ko tas dara, bet bieži vien nevar zināt, kāpēc tas tiek darīts tā.
Šajā nodaļā jūs uzzināsiet, kā ar AI izveidot README, koda komentāru, docstring (komentāru bloks, kas rakstīts katrai funkcijai/klasei), API dokumentu un izmaiņu žurnālu; un kā cilvēciski saglabāt vērtīgāko dokumentācijas daļu: “kāpēc”.
Atšķirība starp "ko" un "kāpēc"
Ir divi dokumentācijas slāņi. Pirmais ir kas/kā: "šī funkcija sakārto sarakstu", "palaist šo komandu, lai instalētu". Tos var iegūt no koda un struktūras; AI šeit ir izcils. Otrkārt, kāpēc: "kāpēc mēs padarījām šo pakalpojumu asinhronu, nevis sinhronu", "kāpēc šī robežvērtība ir 30 sekundes", "kāpēc mēs izvēlējāmies šo bibliotēku, nevis otru". Tie nav ierakstīti kodā; Tas ir dizaina lēmumu, ierobežojumu un pagātnes sāpju rezultāts.
AI nezina "kāpēc"; Labākajā gadījumā tas rada saprātīgu minējumu — kas ir bīstami, jo nepareizs iemesls ir sliktāks par iemesla neesamību. Tātad darba dalīšana ir skaidra: AI izstrādā “kas/kā”, jūs pievienojat “kāpēc”. Visvērtīgākais komentārs ir tas, kas pasaka to, ko kods nevar pateikt.
Padoms. Neatkārtojiet ar komentāru to, ko skaidri saka pats kods (piemēram, i = i + 1 // palieliniet i par vienu). AI dažreiz rada šādus liekus komentārus; Likvidējiet tos un veltiet savu enerģiju komentāriem “kāpēc”.
Soli pa solim: dokumentācijas ģenerēšana ar AI
- Norādiet mērķauditoriju. “Izstrādātājs, kas tikai sāk darbu”, “ārēja komanda, kas izmantos šo API”, “nākotne es” — auditorija nosaka valodu un dziļumu.
- Norādiet avotu. Uzvednei pievienojiet attiecīgo kodu, esošo README, lietojuma piemēru. Dokuments bez avota ir aicinājums izdomāt.
- Uzlikšanas struktūra. Standarta sadaļas README (mērķis, instalēšana, lietojums, konfigurācija, ieguldījums), projekta formāts dokumentu virknei.
- Atzīmējiet atstarpes "kāpēc". Lūdziet AI atzīmēt lēmumus, kuriem tas nezina pamatojumu, kā "šeit ir nepieciešama piezīme "kāpēc"; Tad jūs aizpildiet šīs tukšās vietas.
- Pārbaudīt. Faktiski izpildiet instalēšanas darbības; izmēģiniet koda paraugu. README, kas nedarbojas, ir sliktāks par to, ka README vispār nav.
Trīs mini futrāļi
1. gadījums — README paātrināta ieviešana. Trūka atvērtā pirmkoda rīka README; Jaunie atbalstītāji cīnījās ar instalēšanu vidēji 2 stundas. Komanda nodeva instalēšanas skriptus un package.json AI un izstrādāja strukturētu README, pēc tam pašas veica darbības tīrā datorā un pievienoja divas trūkstošās atkarības. Nākamo atbalstītāju instalēšanas laiks samazinājās līdz vidēji 25 minūtēm.
2. gadījums — izdomātais slazds “kāpēc”. Izstrādātājs lūdza AI komentāru blakus taimauta vērtībai (taimauts = 30). AI uzrakstīja saprātīgu, bet nepareizu pamatojumu "pieļaut lielu tīkla latentumu"; patiesais iemesls bija pakārtotā pakalpojuma līgumā noteiktais 30 sekunžu ierobežojums. Nepareiza interpretācija lika nākamajam izstrādātājam nevajadzīgi palielināt vērtību, izraisot incidentu. Nodarbība: koda īpašniekam ir jāpārbauda pamatojums.
3. gadījums — Docstring standarts ir kļuvis automatizēts. Papildu modulim ar 40 funkcijām nebija dokumentu virkņu. AI tika piešķirts projekta formāts (Google stilā) un katrai funkcijai tika izveidoti parametru, atdeves un izņēmumu apraksti; Izstrādātājs tos pārskatīja un izlaboja dažas nepareizas tipa deklarācijas. 40 funkciju dokumentēšana samazinājās no apmēram pusdienas līdz stundai.
Četras kopējamas veidnes
Strukturēts README melnraksts:
Mērķauditorija: {{piem. jauns līdzautors}}.Uzrakstiet README melnrakstu, pamatojoties uz tālāk norādītajiem failiem. Sadaļas: Mērķis, līdzekļi, prasības, instalēšana, darbība, konfigurācija, testēšana, ieguldījums. Izvilkt instalēšanas / palaišanas komandas no faktiskajiem failiem; MONTĀŽA. Atzīmējiet vietas, par kurām neesat pārliecināts, izmantojot “[VERIFY]”. Avots: {{package.json / skripti / koda paraugs}}
Dokumentu virknes/API atsauce:
Ierakstiet šo funkciju dokumentu virkni {{projekta stils: Google/NumPy/JSDoc}} formātā: īss kopsavilkums, parametri (tips + nozīme), atgriešana, izņēmumi, 1 īss piemērs. Neatkārtojiet to, ko SKAIDRI saka kods. Atzīmējiet dizaina lēmumus, kas prasa "kāpēc" kā "[KĀPĒC VAJADZĪGS]", nerakstiet safabricētu pamatojumu.{{code}}
Noņemiet atstarpes komentāram "kāpēc":
Šajā kodā nākamais izstrādātājs var jautāt "kāpēc tas tā ir?" (maģiski skaitļi, neparasti lēmumi, risinājumi). Katram sniedziet komentāru Skelets, bet pamatojumu atstājiet TUŠU; Es aizpildīšu pamatojumu.{{code}}
Izmaiņu žurnāla/PR paziņojums:
Uzrakstiet {{izmaiņu žurnāla ierakstu / PR apraksts}} no zemāk esošās atšķirības. Formāts: Kas ir mainījies (lietotāja valodā), Kāpēc (problēma: {{...}}), Pārtraucošas izmaiņas (ja tādas ir), Vai tās ir pārbaudītas. Pielāgojiet tehnisko žargonu mērķauditorijai.{{diff}}
Vāja uzvedne / spēcīga uzvedne
Vāji: "Uzrakstiet README šim projektam."
Spēcīga: "Mērķauditorija: izstrādātājs, kurš pirmo reizi klonē šo repo. Pamatojoties uz pievienoto package.json, docker-compose.yml un scripts/ mapi, uzrakstiet README melnrakstu ar sadaļām Mērķis, prasības, instalēšana, darbība, pārbaude, ieguldījums. Izņemiet komandas no šiem failiem, neveidojiet tās ar atzīmi [VERIFY].
Spēcīgā versija sniedz auditoriju, avotu, struktūru un noteikumu “izgatavo, atzīmē to”; lai dokuments būtu balstīts uz reāliem failiem un būtu skaidri redzamas pārbaudāmās vietas.
Dokumenta veids
AI klājas labi
Cilvēks pievieno/pārbauda
README instalēšana
soļa kontūra
Izpildiet darbības un apstipriniet
Docstring/API
Struktūra, parametrs, tips
Pareizais veids un "kāpēc"
Koda komentārs
"Ko viņš dara" kopsavilkums
"Kāpēc tas ir" pamatojums
Izmaiņu žurnāls/PR
pirmais melnraksts
Ietekme un precizitāte
Arhitektūras lēmums (ADR)
skelets
Reāli lēmumi un kompromisi
Dokumentācijai nepieciešama apkope
Visbīstamākais dokumenta aspekts ir tas, ka tas šķiet patiess, lai gan tas ir nepatiess. Kad kods mainās un dokuments netiek atjaunināts, tas aktīvi maldina lasītāju. AI atvieglo atjaunināšanu: izdodiet atšķirību un jautājiet: “kuras dokumenta daļas ietekmē šīs izmaiņas?” jūs varat jautāt. Bet tas ir process, kas nodrošina aktualitāti — padariet dokumentācijas atjaunināšanu par daļu no koda maiņas (PR pieņemšanas kritērijs). AI paātrina; Komanda veido disciplīnu.
Uzmanību! Nepublicējiet, nepārbaudot instalēšanas darbības README. "Iespējams, darba" dokuments var sabojāt jauna izstrādātāja pirmo dienu un iedragāt uzticību. Veiciet darbības pats tīrā vidē.
Biežas kļūdas
- Iegūt “kāpēc” piemērotību AI. Nepatiess pamatojums ir sliktāks par attaisnojuma neesamību; Koda īpašniekam ir jāuzraksta dizaina iemesls.
- Nav pārbaudītas instalēšanas darbības. README, kas nedarbojas, sagrauj uzticību.
- Nevajadzīgs komentārs, kas atkārto kodu. Tas rada troksni, aizsedzot patiesās "kāpēc" interpretācijas.
- Nenorāda mērķauditoriju. Neskaidrs dokuments, kam tas ir rakstīts, nav noderīgs ne iesācējam, ne ekspertam.
- Atjaunināšanas atdalīšana no procesa. Ja dokuments netiek atjaunināts ar kodu, tas ātri kļūst maldinošs.
Rezumējot
AI noņem lielu daļu mehāniskās slodzes no dokumentācijas: ātrie README melnraksti, dokumentācijas virkne, API atsauce, izmaiņu žurnāls un PR apraksti. Bet tas nevar zināt "kāpēc", kas ir visvērtīgākais slānis, un ir bīstami to izdomāt. Darba dalīšana ir skaidra: AI rada “kas/kā”, jūs pievienojat “kāpēc”. Norādiet auditoriju, nodrošiniet resursus, nosakiet struktūru, atzīmējiet vietas un pārbaudiet katru instalēšanas darbību, palaižot to pats. Padariet dokumentāciju par koda maiņas neatņemamu sastāvdaļu.
Lietojumprogrammas uzdevums
Izvēlieties moduli vai nelielu projektu, kura dokumentācijas trūkst vai tā ir novecojusi. Vispirms ģenerējiet kontūru no AI ar “strukturētu README melnrakstu” (vai dokumentu virkni) veidni; Noteikti norādiet avotu un mērķauditoriju. Pēc tam pārejiet cauri katram punktam, kur AI ir atzīmējis [VERIFY] vai [KĀPĒC VAJAG]: faktiski izpildiet iestatīšanas darbības un aizpildiet noformējuma “kāpēc” ar savām zināšanām. Ņemiet vērā, cik darbību ir jālabo un cik “kāpēc” pievienojāt.
kontrolsaraksts
- [ ] Dokumentācijā es nošķiru slāņus "kas/kā" un "kāpēc".
- [ ] Es nedomāju, ka AI veido "kāpēc", es to pievienoju pats.
- [ ] Es norādīju uzvednei mērķauditoriju un faktiskos avota failus.
- [ ] Es pārbaudu AI atzīmētos [VERIFY] punktus, tos izpildot personīgi.
- [ ] Es izslēdzu nevajadzīgos komentārus, kas atkārto kodu.
- [ ] Es veicu dokumentācijas atjaunināšanu par daļu no koda maiņas.