Kasu:
- Võimalus toota README, docstringi ja muudatuste logi mustandeid sihtrühma ja allika põhjal tehisintellektiga
- Võimalus dokumentatsioonis eraldada „mida/kuidas” ja „miks” kihid ning lisada inimesena „miks”
- Kontrollige installietappe, käivitades need isiklikult ja muutes dokumendi koodi muutmise osaks
Tarkvara kõige sagedamini tähelepanuta jäetud, kuid kõige kauem kestvam osa on dokumentatsioon. Kood on loetav ka kuude pärast; Inimene, kes selle kirjutas, on kadunud, kontekst on unustatud ja alles on jäänud vaid see, mis kirjutati. Hea README (sissejuhatav dokument, mis selgitab, mis on projekt ning kuidas seda installida ja käivitada), selgitavad koodi kommentaarid ja ajakohane API dokumentatsioon (viide, mis selgitab liidese kasutamist) määravad otseselt meeskonna töökiiruse. AI eemaldab dokumentatsioonist suure osa kirjutamisväsimusest, kuid sellega kaasneb lõks: AI võib koodi põhjal järeldada, mida see teeb, kuid sageli ei tea, miks see nii on.
Selles üksuses saate teada, kuidas luua AI-ga README, koodikommentaari, dokumendistringi (funktsiooni/klassi kohta kirjutatud kommentaariplokk), API dokumenti ja muudatuste logi; ja kuidas inimlikult säilitada dokumentatsiooni kõige väärtuslikum osa: "miks".
Eristamine "mida" ja "miks" vahel
Dokumentatsioonil on kaks kihti. Esimene on mida/kuidas: "see funktsioon sorteerib nimekirja", "käivita installimiseks see käsk". Neid saab koodist ja struktuurist eraldada; AI on siin suurepärane. Teiseks, miks: "miks me muutsime selle teenuse pigem asünkroonseks kui sünkroonseks", "miks on see piirväärtus 30 sekundit", "miks me valisime selle teegi teise asemel". Neid pole koodis kirjas; See on disainiotsuste, piirangute ja minevikuvalu tulemus.
AI ei tea "miks"; Parimal juhul annab see mõistliku oletuse – mis on ohtlik, sest vale põhjus on hullem kui põhjuseta. Nii et tööjaotus on selge: tehisintellekt koostab "mida/kuidas", lisate "miks". Kõige väärtuslikum kommentaar on see, mis ütleb seda, mida kood öelda ei saa.
Näpunäide: ärge korrake kommentaariga seda, mida kood ise selgelt ütleb (nt i = i + 1 // suurendage i ühe võrra). AI toodab mõnikord selliseid üleliigseid kommentaare; Likvideerige need ja pühendage oma energia "miks" kommentaaridele.
Samm-sammult: dokumentatsiooni loomine tehisintellektiga
- Määrake sihtrühm. „Arendaja, kes alles alustab”, „välismeeskond, kes seda API-t kasutab”, „tulevane mina” – publik määrab keele ja sügavuse tooni.
- Andke allikas. Lisage viipale vastav kood, olemasolev README, kasutusnäide. Allikata dokument on kutse väljamõeldisele.
- Kehtestamise struktuur. Standardsektsioonid README jaoks (eesmärk, installimine, kasutamine, konfiguratsioon, panus), dokumendistringi projektivorming.
- Märkige tühikud "miks". Paluge tehisintellektil märkida otsused, mille põhjendust ta ei tea, kui "siin on vaja märge "miks"; Seejärel täidate need lüngad.
- Kinnitage. Tegelikult käivitage installietapid; proovige näidiskoodi. README, mis ei tööta, on hullem kui üldse mitte README.
Kolm miniümbrist
Juhtum 1 – README kiirendatud sisselülitamine. Avatud lähtekoodiga tööriista README puudus; Uued kaasautorid nägid installiga vaeva keskmiselt 2 tundi. Meeskond andis installiskriptid ja package.json AI-le ning koostas struktureeritud README, seejärel käivitas toimingud ise puhtal masinal ja lisas kaks puuduvat sõltuvust. Järgmiste panustajate installimisaeg vähenes keskmiselt 25 minutini.
Juhtum 2 – väljamõeldud “miks” lõks. Arendaja küsis AI-lt kommentaari ajalõpu väärtuse kõrval (timeout=30). AI kirjutas mõistliku, kuid ebaõige põhjenduse "talumaks suurt võrgu latentsust"; tegelik põhjus oli allavoolu teenuse lepingujärgne 30-sekundiline limiit. Väärtõlgendus pani hilisema arendaja väärtust tarbetult suurendama, mis viis intsidendini. Õppetund: koodi omanik peab kontrollima põhjendust.
Juhtum 3 – Docstringi standard on muutunud automatiseerituks. 40 funktsiooniga abimoodulil ei olnud dokumente. Tehisintellektile anti projekti vorming (Google'i stiil) ja see koostas iga funktsiooni jaoks parameetrite, tagastamiste ja erandite kirjeldused; Arendaja vaatas need üle ja parandas mõned ebaõiged tüübideklaratsioonid. 40 funktsiooni dokumenteerimine langes umbes poolelt päevalt tunnile.
Neli kopeeritavat malli
Struktureeritud README mustand:
Sihtpublik: {{nt. uus kaasautor}}.Kirjutage allolevate failide põhjal mustand README. Jaotised: Eesmärk, funktsioonid, nõuded, installimine, kasutamine, konfigureerimine, testimine, panus. Paigaldus-/käivituskäskude väljavõte tegelikest failidest; PAIGALDAMINE. Märkige kohad, kus te pole kindel, nupuga „[KINNITA]”. Allikas: {{package.json / scripts / näidiskood}}
Docstringi/API viide:
Kirjutage nende funktsioonide dokumentide string vormingus {{projekti stiil: Google/NumPy/JSDoc}}: lühike kokkuvõte, parameetrid (tüüp + tähendus), tagastamine, väljastatud erandid, 1 lühike näide. Ärge korrake seda, mida kood SELGELT ütleb. Märgistage kujundusotsused, mis nõuavad "miks" kui "[MIKS VAJALIK]", ärge kirjutage väljamõeldud põhjendust.{{code}}
Eemaldage tühikud kommentaaride "miks" juurest:
Selles koodis võib järgmine arendaja küsida "miks see nii on?" (maagilised numbrid, ebatavalised otsused, lahendused). Kirjutage igaühe kohta kommentaar Skelett, kuid jätke põhjendus TÜHJA; Täidan põhjenduse.{{code}}
Muudatuste logi/PR avaldus:
Kirjutage allolevast erinevusest {{muudatuste logi kirje / PR kirjeldus}}. Vorming: Mis muutus (kasutaja keeles), Miks (probleem: {{...}}), Katketav muudatus (kui on), Kas seda on testitud. Kohandage tehnilist kõnepruuki vastavalt sihtrühmale.{{diff}}
Nõrk viip / Tugev viip
Nõrk: "Kirjutage selle projekti jaoks README."
Tugev: "Sihtrühm: arendaja, kes kloonib seda repot esimest korda. Kirjutage lisatud package.json, docker-compose.yml ja skriptide/ kausta põhjal README mustand jaotistega Eesmärk, Nõuded, Installimine, Kasutamine, Testimine, Panus. Ekstraheerige käsud nendest failidest, ärge looge neid kindlasti; märkige kohad, kus te pole, [VERIFY]."
Tugev versioon annab publikule, allikale, struktuuri ja “make it, mark it” reegli; nii, et dokument põhineb reaalsetel failidel ja kontrollitavad kohad on selgelt nähtavad.
Dokumendi tüüp
AI-l läheb hästi
Inimene lisab/kontrollib
README installimine
sammu kontuur
Käivitage juhised ja kinnitage
Docstring/API
Struktuur, parameeter, tüüp
Õige tüüp ja "miks"
Koodi kommentaar
"Mida ta teeb" kokkuvõte
"Miks see on" põhjendus
Muudatuste logi/PR
esimene mustand
Mõju ja täpsus
Arhitektuuriotsus (ADR)
skelett
Reaalsed otsused ja kompromissid
Dokumentatsioon nõuab hooldust
Dokumendi kõige ohtlikum aspekt on see, kui see näib tõene, kuigi see on vale. Kui kood muutub ja dokumenti ei uuendata, eksitab see lugejat aktiivselt. Tehisintellekt muudab värskendamise lihtsaks: väljastage erinevus ja küsige, milliseid dokumendi osi see muudatus mõjutab? võite küsida. Kuid see on protsess, mis tagab ajakohasuse – tehke dokumentatsiooni uuendamine osa koodi muutmisest (PR aktsepteerimiskriteerium). AI kiirendab; Meeskond loob distsipliini.
Ettevaatust. Ärge avaldage, kui olete README-s installietapid kontrollinud. "Tõenäoliselt töötav" dokument võib rikkuda uue arendaja esimese tööpäeva ja õõnestada usaldust. Tehke samme ise puhtas keskkonnas.
Levinud vead
- Miks tehisintellektiga sobitamiseks. Vale õigustamine on hullem kui õigustuse puudumine; Koodi omanik peaks kirjutama kujunduse põhjuse.
- Ei kontrolli installietappe. README, mis ei tööta, hävitab usalduse.
- Koodi kordav tarbetu kommentaar. See tekitab müra, varjates tegelikke "miks" tõlgendusi.
- Sihtrühma täpsustamata. Ebaselgest dokumendist, kellele see on kirjutatud, pole kasu ei algajale ega asjatundjale.
- Värskenduse eraldamine protsessist. Kui dokumenti koodiga ei värskendata, muutub see kiiresti eksitavaks.
Kokkuvõttes
AI eemaldab suure osa mehaanilisest koormusest dokumentatsioonist: kiired mustandid README, docstring, API viide, muudatuste logi ja PR kirjeldused. Kuid ta ei saa teada "miks", mis on kõige väärtuslikum kiht, ja selle väljamõtlemine on ohtlik. Tööjaotus on selge: AI toodab "mida/kuidas", lisate "miks". Määrake sihtrühm, pakkuge ressursse, kehtestage struktuur, märkige sobivad kohad ja kontrollige iga installietappi, käivitades seda ise. Muutke dokumentatsioon koodi muutmise lahutamatuks osaks.
Rakenduse ülesanne
Valige moodul või väikeprojekt, mille dokumentatsioon puudub või on aegunud. Esmalt genereerige tehisintellektist struktureeritud README mustandi (või dokumendistringi) malliga ülevaade; Esitage kindlasti allikas ja sihtrühm. Seejärel minge läbi kõik punktid, kus tehisintellekt on märkinud [KINNITA] või [MIKS VAJA]: tegelikult käivitage seadistusetapid ja täitke oma teadmistega kujundus "miks". Pange tähele, kui palju samme tuleb parandada ja kui palju "miks" lisasite.
kontrollnimekiri
- [ ] Dokumentatsioonis eristan "mis/kuidas" ja "miks" kihte.
- [ ] Ma ei tee AI-st "miks", lisan selle ise.
- [ ] Annan viipale sihtrühma ja tegelikud lähtefailid.
- [ ] Kontrollin tehisintellektiga märgitud [VERIFY] punkte, täites need isiklikult.
- [ ] Välistan ebavajalikud kommentaarid, mis kordavad koodi.
- [ ] Muudan dokumentatsiooni värskendamise osa koodimuudatusest.