Dobički:
- Sposobnost izdelave osnutkov README, nizov dokumentov in dnevnikov sprememb na podlagi ciljne publike in vira z umetno inteligenco
- Sposobnost ločevanja plasti »kaj/kako« in »zakaj« v dokumentaciji ter dodajanja »zakaj« kot človeka
- Preverjanje namestitvenih korakov tako, da jih osebno zaženete in naredite dokument del spremembe kode
Najpogosteje zanemarjen, a najdlje trajajoč del programske opreme je dokumentacija. Koda je berljiva tudi po mesecih; Tistega, ki je to napisal, ni več, kontekst je pozabljen in ostalo je le napisano. Dober README (uvodni dokument, ki pojasnjuje, kaj je projekt ter kako ga namestiti in izvajati), pojasnjevalni komentarji kode in posodobljena dokumentacija API-ja (referenca, ki pojasnjuje, kako uporabljati vmesnik) neposredno določajo hitrost ekipe. Umetna inteligenca odpravi veliko "utrujenosti pri pisanju" dokumentacije - vendar prihaja s pastjo: umetna inteligenca lahko iz kode sklepa, kaj počne, vendar pogosto ne more vedeti, zakaj je tako storjena.
V tej enoti se boste naučili izdelati README, komentar kode, niz dokumenta (blok komentarjev, napisan na funkcijo/razred), dokument API in dnevnik sprememb z AI; in kako človeško ohraniti najdragocenejši del dokumentacije: »zakaj«.
Razlika med "kaj" in "zakaj"
Obstajata dve plasti dokumentacije. Prvi je kaj/kako: "ta funkcija razvrsti seznam", "zaženi ta ukaz za namestitev". Te je mogoče izluščiti iz kode in strukture; AI je tu odličen. Drugič, zakaj: "zakaj smo to storitev naredili asinhrono namesto sinhrono", "zakaj je ta mejna vrednost 30 sekund", "zakaj smo izbrali to knjižnico namesto druge". Te niso zapisane v kodi; Je produkt oblikovalskih odločitev, omejitev in preteklih bolečin.
AI ne ve "zakaj"; V najboljšem primeru predstavlja razumno ugibanje - kar je nevarno, saj je napačen razlog hujši kot brez razloga. Torej je delitev dela jasna: umetna inteligenca pripravi osnutek »kaj/kako«, vi dodate »zakaj«. Najbolj dragocen je tisti komentar, ki pove tisto, česar koda ne more povedati.
Namig: s komentarjem ne ponavljajte tega, kar sama koda jasno pove (na primer i = i + 1 // povečajte i za eno). AI včasih ustvari tako odvečne komentarje; Odstranite jih in svojo energijo posvetite komentarjem »zakaj«.
Korak za korakom: Ustvarjanje dokumentacije z AI
- Določite ciljno občinstvo. »Razvijalec, ki šele začenja«, »zunanja ekipa, ki bo uporabljala ta API«, »jaz v prihodnosti« – občinstvo daje ton jeziku in globini.
- Navedite vir. V poziv dodajte ustrezno kodo, obstoječi README, primer uporabe. Dokument brez vira je vabilo k izmišljevanju.
- Struktura nalaganja. Standardni razdelki za README (namen, namestitev, uporaba, konfiguracija, prispevek), oblika projekta za niz dokumentov.
- Označite presledke "zakaj". Prosite AI, da odločitve, za katere ne pozna utemeljitve, označi kot "tukaj je potrebna opomba 'zakaj'"; Nato izpolnite te praznine.
- Preveri. Dejansko zaženite namestitvene korake; preizkusite vzorčno kodo. README, ki ne deluje, je hujši kot brez README-ja.
Trije mini kovčki
Primer 1 – README pospešeno vkrcanje. Manjka README odprtokodnega orodja; Novi sodelavci so se z namestitvijo trudili v povprečju 2 uri. Ekipa je dala namestitvene skripte in package.json AI in sestavila strukturiran README, nato pa sama izvedla korake na čistem stroju in dodala dve manjkajoči odvisnosti. Čas namestitve za naslednje sodelavce se je zmanjšal na povprečno 25 minut.
2. primer – izmišljena past »zakaj«. Razvijalec je prosil AI za komentar poleg vrednosti časovne omejitve (timeout=30). AI je napisal razumno, a nepravilno utemeljitev "tolerirati visoko zakasnitev omrežja"; pravi razlog je bila pogodbena omejitev 30 sekund za nadaljnjo storitev. Zaradi napačne razlage je naslednji razvijalec po nepotrebnem povečal vrednost, kar je povzročilo incident. Lekcija: lastnik kode mora preveriti utemeljitev.
Primer 3 – Standard Docstring je postal avtomatiziran. Pomožni modul s 40 funkcijami ni imel dokumentov. AI je dobil obliko projekta (Googlov slog) in izdelal opise parametrov, povratnih vrednosti in izjem za vsako funkcijo; Razvijalec jih je pregledal in popravil nekaj napačnih deklaracij tipa. Dokumentiranje 40 funkcij se je zmanjšalo s približno pol dneva na eno uro.
Štiri kopirane predloge
Strukturirani osnutek README:
Ciljna publika: {{npr. novi sodelavec}}. Napišite osnutek README na podlagi spodnjih datotek. Razdelki: Namen, Funkcije, Zahteve, Namestitev, Delovanje, Konfiguracija, Testiranje, Prispevek. Izvlecite ukaze za namestitev/zagon iz dejanskih datotek; NAMESTITEV. Označite mesta, za katera niste prepričani, z "[VERIFY]". Vir: {{package.json / skripte / vzorčna koda}}
Referenca Docstring/API:
Napišite niz dokumentov za te funkcije v formatu {{project style: Google/NumPy/JSDoc}}: kratek povzetek, parametri (vrsta + pomen), vrnitev, vržene izjeme, 1 kratek primer. Ne ponavljajte tega, kar koda JASNO pravi. Oblikovalske odločitve, ki zahtevajo "zakaj", označite kot "[ZAKAJ POTREBNO]", ne pišite izmišljene utemeljitve.{{code}}
Odstranite presledke za komentar "zakaj":
V tej kodi se lahko naslednji razvijalec vpraša "zakaj je temu tako?" (magične številke, nenavadne odločitve, rešitve). Za vsako podajte komentar OKOSTJNIK, utemeljitev pa pustite PRAZNO; Izpolnil bom utemeljitev.{{code}}
Dnevnik sprememb/izjava za odnose z javnostmi:
Napišite {{vnos v dnevnik sprememb / PR opis}} iz spodnje razlike. Oblika: Kaj se je spremenilo (v jeziku uporabnika), Zakaj (težava: {{...}}), Lomljiva sprememba (če obstaja), Ali je bilo preizkušeno. Prilagodite tehnični žargon ciljnemu občinstvu.{{diff}}
Šibek poziv/močan poziv
Slabo: "Napišite README za ta projekt."
Močno: "Ciljna skupina: razvijalec, ki prvič klonira ta repo. Na podlagi priloženih package.json, docker-compose.yml in mape scripts/ napišite osnutek README z razdelki Namen, Zahteve, Namestitev, Delovanje, Preizkušanje, Prispevek. Izvlecite ukaze iz teh datotek, ne izmišljujte si; označite vse, kjer niste prepričani, z [VERIFY]."
Močna različica podaja občinstvo, vir, strukturo in pravilo »naredi, označi«; tako da dokument temelji na resničnih datotekah in so mesta, ki jih je treba preveriti, jasno vidna.
Vrsta dokumenta
AI se dobro obnese
Človek doda/preveri
namestitev README
oris koraka
Zaženite korake in potrdite
Docstring/API
Struktura, parameter, vrsta
Pravilna vrsta in "zakaj"
Komentar kode
Povzetek "Kaj počne".
"Zakaj je to" utemeljitev
Dnevnik sprememb/PR
prvi osnutek
Vpliv in natančnost
Arhitekturna odločitev (ADR)
okostje
Resnične odločitve in kompromisi
Dokumentacija zahteva vzdrževanje
Najnevarnejši vidik dokumenta je, ko se zdi resničen, čeprav je napačen. Ko se koda spremeni in dokument ni posodobljen, aktivno zavaja bralca. Umetna inteligenca olajša posodabljanje: izdajte diff in vprašajte »na katere dele dokumenta vpliva ta sprememba?« lahko vprašate. Vendar je postopek tisti, ki zagotavlja ažurnost – naj bo posodobitev dokumentacije del spremembe kode (PR-jevo merilo sprejemljivosti). AI pospešuje; Ekipa gradi disciplino.
Pozor: Ne objavljajte, ne da bi preverili korake namestitve v README. Dokument, ki "verjetno deluje", lahko novemu razvijalcu pokvari prvi dan in spodkopa zaupanje. Sami izvedite korake v čistem okolju.
Pogoste napake
- Pridobivanje »zakaj«, da se prilega AI. Lažna utemeljitev je hujša kot nobena; Lastnik kode mora napisati razlog za načrtovanje.
- Ne preverjam korakov namestitve. README, ki ne deluje, uniči zaupanje.
- Nepotreben komentar ponavlja kodo. Proizvaja hrup in prikrije prave interpretacije "zakaj".
- Brez navedbe ciljne publike. Dokument, za katerega ni jasno, komu je napisan, ni uporaben niti za začetnika niti za strokovnjaka.
- Ločevanje posodobitve od procesa. Če dokument ni posodobljen s kodo, hitro postane zavajajoč.
Če povzamem
Umetna inteligenca odvzame velik del mehanskega bremena dokumentacije: hitri osnutki README, niz dokumentov, sklic na API, dnevnik sprememb in opisi PR. Ne more pa vedeti »zakaj«, ki je najbolj dragocena plast, in si je nevarno izmisliti. Delitev dela je jasna: AI proizvede "kaj/kako", vi dodate "zakaj". Določite občinstvo, zagotovite vire, določite strukturo, označite mesta, ki se prilegajo, in preverite vsak korak namestitve tako, da ga izvedete sami. Naj bo dokumentacija sestavni del spremembe kode.
Aplikacijska naloga
Izberite modul ali manjši projekt, katerega dokumentacija manjka ali je zastarela. Najprej ustvarite oris iz AI s predlogo »strukturiranega osnutka README« (ali niza dokumentov); Ne pozabite navesti vira in ciljne skupine. Nato pojdite skozi vsako točko, kjer je umetna inteligenca označila [VERIFY] ali [WHY NEEDED]: dejansko zaženite nastavitvene korake in izpolnite načrt »zakaj« s svojim znanjem. Upoštevajte, koliko korakov je treba popraviti in koliko "zakaj" ste dodali.
kontrolni seznam
- [ ] V dokumentaciji ločim plasti "kaj/kako" in "zakaj".
- [] Ne prisilim AI, da izmisli "zakaj", dodam ga sam.
- [ ] Pozivu dam ciljno občinstvo in dejanske izvorne datoteke.
- [ ] Točke [VERIFY], ki jih je označil AI, preverim tako, da jih osebno izvedem.
- [ ] Izločim nepotrebne komentarje, ki ponavljajo kodo.
- [ ] Posodobitev dokumentacije je del spremembe kode.