zisky:
- Schopnosť produkovať README, dokumentačný reťazec a návrh protokolu zmien na základe cieľového publika a zdroja pomocou AI
- Schopnosť oddeliť vrstvy „čo/ako“ a „prečo“ v dokumentácii a pridať „prečo“ ako človek
- Overenie krokov inštalácie ich osobným spustením a vytvorením dokumentu súčasťou zmeny kódu
Najčastejšie zanedbávanou, no najdlhšie trvajúcou časťou softvéru je dokumentácia. Kód je čitateľný aj po mesiacoch; Osoba, ktorá to napísala, je preč, kontext je zabudnutý a zostáva len to, čo bolo napísané. Dobrý README (úvodný dokument, ktorý vysvetľuje, čo je projekt a ako ho nainštalovať a spustiť), vysvetľujúce komentáre ku kódu a aktuálna dokumentácia API (odkaz, ktorý vysvetľuje, ako používať rozhranie) priamo určuje rýchlosť tímu. Umelá inteligencia odstraňuje veľa „únavy pri písaní“ z dokumentácie – prichádza však s pascou: AI dokáže z kódu odvodiť, čo robí, ale často nevie, prečo sa to tak robí.
V tejto lekcii sa naučíte, ako vytvárať README, komentár ku kódu, docstring (blok komentárov napísaný podľa funkcie/triedy), API dokument a changelog pomocou AI; a ako ľudsky zachovať najcennejšiu časť dokumentácie: „prečo“.
Rozdiel medzi „Čo“ a „Prečo“
Existujú dve vrstvy dokumentácie. Prvým je čo/ako: „táto funkcia triedi zoznam“, „spustite tento príkaz na inštaláciu“. Tie možno extrahovať z kódu a štruktúry; AI tu exceluje. Po druhé, prečo: „prečo sme urobili túto službu asynchrónnou a nie synchrónnou“, „prečo je táto limitná hodnota 30 sekúnd“, „prečo sme si vybrali túto knižnicu pred druhou“. Tieto nie sú zapísané v kóde; Je to produkt návrhových rozhodnutí, obmedzení a minulých bolestí.
AI nevie „prečo“; V najlepšom prípade ide o rozumný odhad – čo je nebezpečné, pretože nesprávny dôvod je horší ako žiadny dôvod. Rozdelenie práce je teda jasné: AI navrhuje „čo/ako“, vy pridáte „prečo“. Najcennejší komentár je ten, ktorý hovorí to, čo kód nemôže povedať.
Tip: Neopakujte s komentárom to, čo jasne hovorí samotný kód (napríklad i = i + 1 // zvýšenie i o jeden). AI niekedy produkuje takéto nadbytočné komentáre; Odstráňte ich a venujte svoju energiu komentárom „prečo“.
Krok za krokom: Generovanie dokumentácie pomocou AI
- Špecifikujte cieľové publikum. „Vývojár, ktorý práve začína“, „externý tím, ktorý bude používať toto API“, „ja budúcnosť“ – publikum udáva tón pre jazyk a hĺbku.
- Daj zdroj. Do výzvy pridajte príslušný kód, existujúci súbor README, príklad použitia. Dokument bez zdroja je pozvánkou na výrobu.
- Štruktúra uloženia. Štandardné sekcie pre README (účel, inštalácia, použitie, konfigurácia, príspevok), formát projektu pre dokumentačný reťazec.
- Označte medzery „prečo“. Požiadajte AI, aby označila rozhodnutia, pre ktoré nepozná odôvodnenie, ako „tu je potrebná poznámka „prečo“; Potom vyplňte tieto prázdne miesta.
- Overiť. V skutočnosti spustite inštalačné kroky; vyskúšajte ukážkový kód. README, ktoré nefunguje, je horšie ako žiadne README.
Tri mini puzdrá
Prípad 1 – Zrýchlené začlenenie do súboru README. Chýbal súbor README open source nástroja; Noví prispievatelia zápasili s inštaláciou v priemere 2 hodiny. Tím dal inštalačné skripty a súbor package.json AI a navrhol štruktúrovaný súbor README, potom spustil samotné kroky na čistom počítači a pridal dve chýbajúce závislosti. Čas inštalácie pre ďalších prispievateľov sa skrátil v priemere na 25 minút.
Prípad 2 – Vymyslená pasca „prečo“. Vývojár požiadal AI o komentár vedľa hodnoty časového limitu (timeout=30). AI napísala rozumné, ale nesprávne odôvodnenie „tolerovať vysokú latenciu siete“; skutočným dôvodom bol zmluvný 30-sekundový limit nadväzujúcej služby. Nesprávna interpretácia viedla následného vývojára k zbytočnému zvýšeniu hodnoty, čo viedlo k incidentu. Poučenie: vlastník kódu musí overiť odôvodnenie.
Prípad 3 – Štandard Docstring sa zautomatizoval. Pomocný modul so 40 funkciami nemal žiadne dokumentačné reťazce. Umelá inteligencia dostala formát projektu (štýl Google) a vytvorila popis parametrov, návratnosti a výnimiek pre každú funkciu; Vývojár ich skontroloval a opravil niekoľko nesprávnych vyhlásení o type. Dokumentácia 40 funkcií klesla z približne pol dňa na hodinu.
Štyri kopírovateľné šablóny
Štruktúrovaný koncept README:
Cieľové publikum: {{napr. nový prispievateľ}}.Napíšte koncept README na základe nižšie uvedených súborov. Sekcie: Účel, Vlastnosti, Požiadavky, Inštalácia, Prevádzka, Konfigurácia, Testovanie, Príspevok. Extrahujte inštalačné/spúšťacie príkazy zo skutočných súborov; VYBAVENIE. Označte miesta, o ktorých si nie ste istí, pomocou „[VERIFY]“. Zdroj: {{package.json / scripts / sample code}}
Referenčný reťazec dokumentu/API:
Napíšte docstring k týmto funkciám vo formáte {{project style: Google/NumPy/JSDoc}}: krátke zhrnutie, parametre (typ + význam), návrat, vyvolané výnimky, 1 krátky príklad. Neopakujte, čo kód JASNE hovorí. Označte rozhodnutia o dizajne, ktoré vyžadujú „prečo“ ako „[PREČO NUTNÉ]“, nepíšte vymyslené odôvodnenie.{{code}}
Odstráňte medzery pre komentár „prečo“:
V tomto kóde sa ďalší vývojár môže spýtať "prečo je to tak?" (magické čísla, nezvyčajné rozhodnutia, riešenia). Ku každému uveďte komentár KOSTRA, ale zdôvodnenie nechajte PRÁZDNE; Vyplním odôvodnenie.{{code}}
Changelog/PR vyhlásenie:
Napíšte {{changelog entry / PR description}} z nižšie uvedeného rozdielu. Formát: Čo sa zmenilo (v jazyku používateľa), Prečo (vydanie: {{...}}), Prelomová zmena (ak existuje), Bolo to testované. Prispôsobte technický žargón cieľovému publiku.{{diff}}
Slabá výzva / Silná výzva
Slabý: "Napíšte README pre tento projekt."
Strong: "Cieľové publikum: vývojár, ktorý po prvýkrát klonuje toto repo. Na základe priloženého súboru package.json, docker-compose.yml a priečinka scripts/ napíšte koncept README s časťami Účel, Požiadavky, Inštalácia, Operácia, Testovanie, Príspevok. Extrahujte príkazy z týchto súborov, nevymýšľajte si ich; označte kdekoľvek, kde si nie ste istí, pomocou [VERIFY]."
Silná verzia dáva publiku, zdroj, štruktúru a pravidlo „vyrob to, označ to“; aby dokument vychádzal zo skutočných spisov a miesta, ktoré sa majú overiť, boli jasne viditeľné.
Typ dokumentu
AI robí dobre
Človek pridáva/overuje
Inštalácia README
osnova krokov
Spustite kroky a potvrďte
Docstring/API
Štruktúra, parameter, typ
Správny typ a „prečo“
Komentár kódu
Zhrnutie „Čo robí“.
"Prečo je to" odôvodnenie
Changelog/PR
prvý návrh
Účinok a presnosť
Architektonické rozhodnutie (ADR)
kostra
Skutočné rozhodnutia a kompromisy
Dokumentácia vyžaduje údržbu
Najnebezpečnejším aspektom dokumentu je, keď sa javí ako pravdivý, aj keď je nepravdivý. Keď sa kód zmení a dokument nie je aktualizovaný, aktívne zavádza čitateľa. Umelá inteligencia uľahčuje aktualizáciu: zadajte rozdiel a opýtajte sa „ktoré časti dokumentu ovplyvňuje táto zmena?“ môžete sa opýtať. Ale je to proces, ktorý zabezpečuje aktuálnosť – urobte aktualizáciu dokumentácie súčasťou zmeny kódu (akceptačné kritérium PR). AI zrýchľuje; Tým si buduje disciplínu.
Upozornenie: Nepublikujte bez overenia inštalačných krokov v súbore README. Dokument „pravdepodobne funguje“ môže pokaziť prvý deň nového vývojára a naštrbiť dôveru. Spustite kroky sami v čistom prostredí.
Časté chyby
- Získanie „prečo“ na prispôsobenie AI. Falošné ospravedlnenie je horšie ako žiadne ospravedlnenie; Vlastník kódu by mal napísať dôvod návrhu.
- Neoveruje sa postup inštalácie. README, ktoré nefunguje, ničí dôveru.
- Zbytočný komentár opakujúci kód. Produkuje hluk, ktorý zakrýva skutočné interpretácie „prečo“.
- Bez špecifikácie cieľového publika. Dokument, ktorému nie je jasné, komu je napísaný, nie je pre začiatočníka ani odborníka užitočný.
- Oddelenie aktualizácie od procesu. Ak dokument nie je aktualizovaný kódom, rýchlo sa stáva zavádzajúcim.
V súhrne
Umelá inteligencia odstraňuje veľkú časť mechanickej záťaže z dokumentácie: rýchle návrhy README, dokumentačný reťazec, referencie API, protokol zmien a popisy PR. Ale nemôže vedieť „prečo“, čo je najcennejšia vrstva a je nebezpečné si ju vymýšľať. Rozdelenie práce je jasné: AI produkuje „čo/ako“, pridáte „prečo“. Špecifikujte publikum, poskytnite zdroje, vložte štruktúru, označte miesta, ktoré sa hodia, a overte každý krok inštalácie spustením sami. Urobte z dokumentácie neoddeliteľnú súčasť zmeny kódu.
Aplikačná úloha
Vyberte modul alebo malý projekt, ktorého dokumentácia chýba alebo je zastaraná. Najprv vygenerujte osnovu z AI pomocou šablóny „štruktúrovaného návrhu README“ (alebo dokumentačného reťazca); Nezabudnite uviesť zdroj a cieľové publikum. Potom prejdite každým bodom, kde AI označila [VERIFY] alebo [PREČO POTREBNÉ]: v skutočnosti spustite kroky nastavenia a vyplňte „prečo“ návrhu svojimi vlastnými znalosťami. Všimnite si, koľko krokov je potrebné opraviť a koľko „prečo“ ste pridali.
kontrolný zoznam
- [ ] V dokumentácii rozlišujem vrstvy „čo/ako“ a „prečo“.
- [ ] Nerobím, aby AI vymýšľala „prečo“, pridávam to sám.
- [ ] Výzve dávam cieľové publikum a skutočné zdrojové súbory.
- [ ] Body [VERIFY] označené AI si overujem tak, že ich osobne vykonám.
- [ ] Odstraňujem zbytočné komentáre, ktoré opakujú kód.
- [ ] Aktualizáciu dokumentácie robím súčasťou zmeny kódu.