Pelnas:
- Galimybė kurti README, docstring ir pakeitimų žurnalo juodraščius pagal tikslinę auditoriją ir šaltinį naudojant AI
- Galimybė dokumentuose atskirti „kas/kaip“ ir „kodėl“ sluoksnius ir pridėti „kodėl“ kaip žmogus.
- Patvirtinkite diegimo veiksmus asmeniškai juos paleisdami ir įtraukdami dokumentą į kodo keitimo dalį
Dažniausiai apleista, bet ilgiausiai trunkanti programinės įrangos dalis yra dokumentacija. Kodas skaitomas net po mėnesių; Žmogaus, kuris jį parašė, nebėra, kontekstas pasimiršta ir lieka tik tai, kas parašyta. Geras README (įvadinis dokumentas, paaiškinantis, kas yra projektas ir kaip jį įdiegti bei paleisti), aiškinamieji kodo komentarai ir naujausia API dokumentacija (nuoroda, paaiškinanti, kaip naudotis sąsaja) tiesiogiai lemia komandos greitį. Dirbtinis intelektas atima daug „rašymo nuovargio“ iš dokumentacijos, tačiau tai yra spąstai: dirbtinis intelektas iš kodo gali daryti išvadą, ką jis daro, bet dažnai negali žinoti, kodėl taip daroma.
Šiame skyriuje sužinosite, kaip sukurti README, kodo komentarą, dokumentų eilutę (komentarų blokas, parašytas kiekvienai funkcijai / klasei), API dokumentą ir pakeitimų žurnalą su AI; ir kaip žmogiškai išsaugoti vertingiausią dokumentacijos dalį: „kodėl“.
Skirtumas tarp "kas" ir "kodėl"
Yra du dokumentai. Pirmasis yra kas/kaip: „ši funkcija surūšiuoja sąrašą“, „paleiskite šią komandą, kad įdiegtumėte“. Juos galima išgauti iš kodo ir struktūros; AI čia puikiai tinka. Antra, kodėl: „kodėl šią paslaugą padarėme asinchronine, o ne sinchronine“, „kodėl ši riba yra 30 sekundžių“, „kodėl pasirinkome šią biblioteką, o ne kitą“. Tai neparašyta kode; Tai dizaino sprendimų, suvaržymų ir praeities skausmo rezultatas.
AI nežino „kodėl“; Geriausiu atveju tai daro pagrįstą spėjimą – o tai pavojinga, nes neteisinga priežastis yra blogiau nei jokios priežasties. Taigi darbo pasidalijimas yra aiškus: AI parengia „kas/kaip“, jūs pridedate „kodėl“. Vertingiausias komentaras yra tas, kuris pasako tai, ko kodas negali pasakyti.
Patarimas: nekartokite su komentaru to, ką aiškiai sako pats kodas (pvz., i = i + 1 // padidinkite i vienu). AI kartais pateikia tokius perteklinius komentarus; Pašalinkite juos ir skirkite savo energiją komentarams „kodėl“.
Žingsnis po žingsnio: dokumentų generavimas naudojant AI
- Nurodykite tikslinę auditoriją. „Kūrėjas ką tik pradedantis“, „išorinė komanda, kuri naudos šią API“, „būsimas aš“ – auditorija nustato kalbos ir gylio toną.
- Pateikite šaltinį. Į raginimą pridėkite atitinkamą kodą, esamą README, naudojimo pavyzdį. Dokumentas be šaltinio yra kvietimas gaminti.
- Primetimo struktūra. Standartiniai skyriai, skirti README (tikslas, diegimas, naudojimas, konfigūracija, įnašas), projekto formatas, skirtas dokumentams.
- Pažymėkite tarpus „kodėl“. Paprašykite AI pažymėti sprendimus, kurių pagrindimo jis nežino, kaip „čia reikalinga pastaba „kodėl“; Tada užpildykite tuos tarpus.
- Patvirtinti. Iš tikrųjų paleiskite diegimo veiksmus; pabandykite pavyzdinį kodą. README, kuris neveikia, yra blogesnis nei joks README.
Trys mini dėklai
1 atvejis – README pagreitintas įjungimas. Trūko atvirojo kodo įrankio README; Nauji bendradarbiai diegdami vargo vidutiniškai 2 valandas. Komanda atidavė AI diegimo scenarijus ir package.json ir parengė struktūrizuotą README, tada patys atliko veiksmus švariame kompiuteryje ir pridėjo dvi trūkstamas priklausomybes. Kitų bendraautorių diegimo laikas sumažėjo iki vidutiniškai 25 minučių.
2 atvejis – sugalvoti „kodėl“ spąstai. Kūrėjas paprašė AI pakomentuoti šalia skirtojo laiko vertės (laikas = 30). AI parašė pagrįstą, bet neteisingą pagrindimą „toleruoti didelę tinklo delsą“; tikroji priežastis buvo tolesnių paslaugų sutartyje nustatytas 30 sekundžių limitas. Dėl klaidingo aiškinimo paskesnis kūrėjas be reikalo padidino vertę, todėl įvyko incidentas. Pamoka: kodo savininkas turi patikrinti pagrindimą.
3 atvejis – Docstring standartas tapo automatizuotas. Pagalbinis modulis su 40 funkcijų neturėjo dokumentų eilučių. AI buvo suteiktas projekto formatas („Google“ stilius) ir kiekvienai funkcijai buvo sukurti parametrų, grąžinimo ir išimčių aprašymai; Kūrėjas juos peržiūrėjo ir ištaisė keletą neteisingų tipų deklaracijų. 40 funkcijų dokumentavimas sumažėjo nuo maždaug pusės dienos iki valandos.
Keturi kopijuojami šablonai
Struktūrinis README juodraštis:
Tikslinė auditorija: {{pvz. naujas bendradarbis}}.Parašykite juodraštį README, remdamiesi toliau pateiktais failais. Skyriai: Paskirtis, Savybės, Reikalavimai, Diegimas, Eksploatacija, Konfigūracija, Testavimas, Įnašas. Ištraukite diegimo / vykdymo komandas iš tikrųjų failų; MONTAVIMAS. Pažymėkite vietas, kuriose nesate tikri, naudodami „[PATIKRINTI]“. Šaltinis: {{package.json / scripts / pavyzdinis kodas}}
Dokumentų eilutės / API nuoroda:
Įrašykite šių funkcijų dokumentų eilutę {{projekto stilius: Google/NumPy/JSDoc}} formatu: trumpa santrauka, parametrai (tipas + reikšmė), grąžinimas, išimtys, 1 trumpas pavyzdys. Nekartokite to, ką AIŠKIAI sako kodas. Projektavimo sprendimus, kuriuose reikalaujama „kodėl“, pažymėkite kaip „[KODĖL REIKIA]“, nerašykite išgalvoto pagrindimo.{{code}}
Pašalinkite tarpus prie komentaro „kodėl“:
Šiame kode kitas kūrėjas gali paklausti „kodėl taip? (stebuklingi skaičiai, neįprasti sprendimai, problemos sprendimo būdai). Pateikite komentarą SKELETAS kiekvienam, bet palikite pagrindimą TUŠČIĄ; Aš užpildysiu pagrindimą.{{code}}
Pakeitimų žurnalas / PR pareiškimas:
Parašykite {{pakeitimų žurnalo įrašas / PR aprašymas}} iš skirtuko žemiau. Formatas: kas pasikeitė (vartotojo kalba), kodėl (problema: {{...}}), stabdomas pakeitimas (jei yra), ar jis buvo išbandytas. Pritaikykite techninį žargoną tikslinei auditorijai.{{diff}}
Silpnas raginimas / Stiprus raginimas
Silpna: „Parašykite README šiam projektui“.
Stiprus: "Tikslinė auditorija: kūrėjas, pirmą kartą klonuojantis šį atpirkimą. Remdamiesi pridėtu paketu.json, docker-compose.yml ir aplanku scripts/, parašykite README juodraštį su skyriais Tikslas, Reikalavimai, Diegimas, Operacija, Testavimas, Įnašas. Ištraukite komandas iš šių failų, nesukurkite jų; pažymėkite [VERIFY], kur nesate.
Stiprioji versija suteikia auditoriją, šaltinį, struktūrą ir taisyklę „padaryk, pažymėk“; kad dokumentas būtų pagrįstas tikromis bylomis ir būtų aiškiai matomos tikrintinos vietos.
Dokumento tipas
AI veikia gerai
Žmogus prideda / patikrina
README diegimas
žingsnio kontūras
Atlikite veiksmus ir patvirtinkite
Docstring / API
Struktūra, parametras, tipas
Teisingas tipas ir "kodėl"
Kodo komentaras
„Ką jis daro“ santrauka
„Kodėl tai yra“ pagrindimas
Pakeitimų žurnalas/PR
pirmasis juodraštis
Poveikis ir tikslumas
Architektūrinis sprendimas (ADR)
skeletas
Realūs sprendimai ir kompromisai
Dokumentacijai reikalinga techninė priežiūra
Pavojingiausias dokumento aspektas yra tada, kai jis atrodo teisingas, nors jis yra klaidingas. Kai kodas keičiasi ir dokumentas neatnaujinamas, jis aktyviai klaidina skaitytoją. AI palengvina atnaujinimą: išduokite skirtumą ir paklauskite „kurioms dokumento dalims įtakos turi šis pakeitimas? galite paklausti. Tačiau tai yra procesas, kuris užtikrina naujausią – dokumentacijos atnaujinimą paverskite kodo keitimo dalimi (PR priėmimo kriterijus). AI pagreitina; Komanda kuria discipliną.
Įspėjimas: neskelbkite nepatikrinę diegimo veiksmų README. „Tikriausiai darbo“ dokumentas gali sugadinti pirmąją naujojo kūrėjo darbo dieną ir pakirsti pasitikėjimą. Atlikite veiksmus patys švarioje aplinkoje.
Dažnos klaidos
- „Kodėl“, kad jis atitiktų AI. Klaidingas pateisinimas yra blogesnis už nepateisinimą; Kodo savininkas turėtų parašyti dizaino priežastį.
- Nepatikrinama diegimo veiksmų. README, kuris neveikia, griauna pasitikėjimą.
- Nereikalingas komentaras, kartojantis kodą. Tai sukelia triukšmą, užgožia tikrąsias „kodėl“ interpretacijas.
- Tikslinės auditorijos nenurodymas. Dokumentas, kuris neaiškus, kam jis parašytas, nėra naudingas nei naujokui, nei ekspertui.
- Atnaujinimo atskyrimas nuo proceso. Jei dokumentas neatnaujinamas su kodu, jis greitai tampa klaidinantis.
Apibendrinant
AI pašalina didžiąją dalį mechaninės dokumentacijos naštos: greiti README juodraščiai, dokumentų eilutė, API nuoroda, pakeitimų žurnalas ir viešųjų ryšių aprašai. Tačiau ji negali žinoti „kodėl“, kuris yra pats vertingiausias sluoksnis, ir jį išgalvoti pavojinga. Darbo pasidalijimas yra aiškus: AI sukuria „kas/kaip“, jūs pridedate „kodėl“. Nurodykite auditoriją, pateikite išteklius, nustatykite struktūrą, pažymėkite tinkamas vietas ir patikrinkite kiekvieną diegimo veiksmą vykdydami patys. Padarykite dokumentaciją neatsiejama kodo keitimo dalimi.
Taikymo užduotis
Pasirinkite modulį arba nedidelį projektą, kurio dokumentacijos trūksta arba kurie pasenę. Pirmiausia sugeneruokite kontūrą iš AI naudodami „struktūrizuoto README juodraščio“ (arba dokumentų eilutės) šabloną; Būtinai nurodykite šaltinį ir tikslinę auditoriją. Tada atlikite kiekvieną tašką, kuriame AI pažymėjo [PATIKRINTI] arba [KODĖL REIKIA]: iš tikrųjų atlikite sąrankos veiksmus ir savo žiniomis užpildykite dizaino „kodėl“. Atkreipkite dėmesį, kiek veiksmų reikia pataisyti ir kiek „kodėl“ pridėjote.
kontrolinis sąrašas
- [ ] Dokumentacijoje skiriu sluoksnius „kas/kaip“ ir „kodėl“.
- [ ] Aš nesudarau AI „kodėl“, pridedu jį pats.
- [ ] Pateikiu raginimą tikslinę auditoriją ir tikrus šaltinio failus.
- [ ] Aš patikrinu [VERIFY] taškus, pažymėtus AI, asmeniškai juos vykdydamas.
- [ ] Pašalinu nereikalingus komentarus, kurie kartoja kodą.
- [ ] Kodo keitimo dalimi darau dokumentacijos atnaujinimą.