Nyereség:
- Képes README, docstring és változásnapló-vázlatok előállítására a célközönség és a forrás alapján AI segítségével
- Lehetőség a "mit/hogyan" és a "miért" rétegek szétválasztására a dokumentációban, és a "miért" hozzáadására emberként
- A telepítési lépések ellenőrzése személyes futtatással, és a dokumentumnak a kódmódosítás részévé tételével
A szoftver leggyakrabban elhanyagolt, de leghosszabb ideig tartó része a dokumentáció. A kód hónapok után is olvasható; Eltűnt az, aki írta, a szövegkörnyezet feledésbe merült, és csak az maradt meg, amit leírtak. Egy jó README (bevezető dokumentum, amely elmagyarázza, mi a projekt, hogyan kell telepíteni és futtatni), a magyarázó kód megjegyzései és egy naprakész API-dokumentáció (egy interfész használatát ismertető hivatkozás) közvetlenül meghatározza a csapat sebességét. A mesterséges intelligencia sok „írási fáradtságot” vesz el a dokumentációból – de van benne egy csapda: az AI kikövetkezhet a kódból, hogy mit csinál, de gyakran nem tudja, miért csinálják így.
Ebben az egységben megtanulhatja, hogyan állíthat elő README, kód megjegyzést, docstringet (függvényenként/osztályonként írt megjegyzésblokk), API dokumentumot és változásnaplót AI-val; és hogyan őrizhetjük meg emberileg a dokumentáció legértékesebb részét: a „miért”-et.
Különbség a "mit" és a "miért" között
A dokumentációnak két rétege van. Az első a mit/hogyan: "ez a függvény rendezi a listát", "futtassa ezt a parancsot a telepítéshez". Ezek a kódból és a szerkezetből kinyerhetők; Az AI itt remekel. Másodszor, miért: "miért tettük ezt a szolgáltatást aszinkronnak, nem pedig szinkronnak", "miért 30 másodperc ez a határérték", "miért választottuk ezt a könyvtárat a másikkal szemben". Ezek nincsenek beleírva a kódba; Tervezési döntések, korlátok és múltbeli fájdalom eredménye.
A mesterséges intelligencia nem tudja, "miért"; Legjobb esetben is ésszerű feltételezésből adódik – ami veszélyes, mert a rossz ok rosszabb, mint az ok hiánya. Tehát a munkamegosztás egyértelmű: a mesterséges intelligencia megszerkeszti a „mit/hogyan”-t, te pedig hozzáadod a „miért”. A legértékesebb megjegyzés az, ami azt mondja, amit a kód nem tud.
Tipp: Ne ismételje meg megjegyzéssel azt, amit maga a kód egyértelműen mond (például i = i + 1 // növelje i-t eggyel). Az AI néha ilyen redundáns megjegyzéseket produkál; Távolítsa el őket, és fordítsa energiáját a „miért” megjegyzésekre.
Lépésről lépésre: Dokumentáció generálása mesterséges intelligencia segítségével
- Adja meg a célközönséget. „Egy most induló fejlesztő”, „a külső csapat, amely ezt az API-t fogja használni”, „a jövő én” – a közönség adja meg a nyelvezet és a mélység alaphangját.
- Add meg a forrást. Adja hozzá a megfelelő kódot, a meglévő README, használati példát a prompthoz. A forrás nélküli dokumentum felhívás a gyártásra.
- Kivetési szerkezet. Szabványos szakaszok a README (Cél, Telepítés, Használat, Konfiguráció, Hozzájárulás) számára, a docstring projektformátuma.
- Jelölje be a „miért” szóközöket. Kérje meg az MI-t, hogy jelölje meg azokat a döntéseket, amelyeknek nem ismeri az indoklását, mint „itt egy „miért” megjegyzés szükséges”; Ezután töltse ki ezeket az üres helyeket.
- Ellenőrizze. Valójában futtassa a telepítési lépéseket; próbáld ki a mintakódot. A nem működő README rosszabb, mint a README hiánya.
Három mini tok
1. eset – A README gyorsított beépítése. Egy nyílt forráskódú eszköz README-je hiányzott; Az új közreműködők átlagosan 2 órát küzdöttek a telepítéssel. A csapat átadta a telepítő szkripteket és a package.json fájlt az AI-nak, és elkészített egy strukturált README-t, majd lefuttatta a lépéseket egy tiszta gépen, és hozzáadta a két hiányzó függőséget. A következő közreműködők telepítési ideje átlagosan 25 percre csökkent.
2. eset – A kitalált „miért” csapda. Egy fejlesztő megjegyzést kért az AI-tól egy időtúllépési érték mellé (timeout=30). Az AI ésszerű, de helytelen indoklást írt "a magas hálózati késleltetés elviselésére"; a valódi ok egy downstream szolgáltatás szerződéses 30 másodperces korlátja volt. A félreértelmezés arra késztette a későbbi fejlesztőt, hogy szükségtelenül növelje az értéket, ami incidenshez vezetett. Tanulság: a kód tulajdonosának ellenőriznie kell az indoklást.
3. eset – A Docstring szabvány automatizálódott. Egy 40 funkciós kiegészítő modulnak nem volt docstringje. Az AI megkapta a projekt formátumát (Google stílus), és paraméter-, visszatérési- és kivételleírásokat készített minden egyes funkcióhoz; A fejlesztő áttekintette ezeket, és kijavított néhány helytelen típusdeklarációt. 40 funkció dokumentálása körülbelül fél napról egy órára csökkent.
Négy másolható sablon
Strukturált README vázlat:
Célközönség: {{pl. új közreműködő}}. Írjon egy OLVASÁSI tervezetet az alábbi fájlok alapján. Szakaszok: Cél, Szolgáltatások, Követelmények, Telepítés, Működés, Konfiguráció, Tesztelés, Hozzájárulás. Telepítési/futtatási parancsok kibontása tényleges fájlokból; FELSZERELÉS. Jelölje meg azokat a helyeket, amelyekben nem vagy biztos az „[VERIFY]” funkcióval. Forrás: {{package.json / scripts / mintakód}}
Dokumentumkarakterlánc/API hivatkozás:
Írjon docstringet ezekhez a függvényekhez {{projektstílus: Google/NumPy/JSDoc}} formátumban: rövid összefoglaló, paraméterek (típus + jelentés), visszatérés, kivételek dobása, 1 rövid példa. Ne ismételje meg azt, amit a kód TISZTÁN mond. A „miért”-t igénylő tervezési döntéseket „[MIÉRT SZÜKSÉGES]”-ként jelölje meg, ne írjon koholt indoklást.{{code}}
Távolítsa el a szóközöket a „miért” megjegyzésnél:
Ebben a kódban a következő fejlesztő megkérdezheti, hogy "miért van ez így?" (varázsszámok, szokatlan döntések, megoldások). Mindegyikhez adjon megjegyzést CSONETON, de az indoklást hagyja ÜRES; Ki fogom tölteni az indoklást.{{code}}
Változásnapló/PR nyilatkozat:
Írjon egy {{módosítási bejegyzés / PR leírás}} az alábbi különbségből. Formátum: Mi változott (felhasználói nyelven), Miért (probléma: {{...}}), Megszakító változás (ha van), Tesztelték-e. Módosítsa a szakzsargont a célközönséghez.{{diff}}
Gyenge felszólítás / Erős felszólítás
Gyenge: "Írjon README-t ehhez a projekthez."
Erős: "Célközönség: egy fejlesztő, aki először klónozza ezt a repót. A mellékelt package.json, docker-compose.yml és scripts/ mappa alapján írjon egy README vázlatot a Cél, Követelmények, Telepítés, Működés, Tesztelés, Hozzájárulás szakaszokkal. Bontsa ki a parancsokat ezekből a fájlokból, ne állítsa be őket; jelölje be a [VERIFY] karakterrel mindenhol, ahol nem vagy.
Az erős változat megadja a közönséget, a forrást, a szerkezetet és a „készítsd, jelöld meg” szabályt; hogy a dokumentum valós állományokra épüljön, és jól láthatóak legyenek az ellenőrizendő helyek.
Dokumentum típusa
Az AI jól működik
Ember ad hozzá/ellenőrzi
README telepítés
lépés vázlata
Futtassa a lépéseket, és erősítse meg
Docsstring/API
Szerkezet, paraméter, típus
Helyes típus és "miért"
Kód megjegyzés
"Mit csinál" összefoglaló
"Miért ez" indoklás
Változásnapló/PR
első tervezet
Hatás és pontosság
Építészeti döntés (ADR)
csontváz
Valódi döntések és kompromisszumok
A dokumentáció karbantartást igényel
A dokumentum legveszélyesebb aspektusa az, amikor igaznak tűnik, még akkor is, ha hamis. Amikor a kód megváltozik, és a dokumentumot nem frissítik, az aktívan félrevezeti az olvasót. A mesterséges intelligencia megkönnyíti a frissítést: adjon ki egy diff-et, és kérdezze meg, hogy „a dokumentum mely részeit érinti ez a változás?” kérdezhetsz. De ez a folyamat biztosítja a naprakészséget – tegye a dokumentáció frissítését a kódmódosítás részévé (a PR elfogadási feltétele). Az AI felgyorsul; A csapat fegyelmet épít.
Vigyázat: Ne tegye közzé a telepítés lépéseinek ellenőrzése nélkül a README-ban. Egy "valószínűleg működő" dokumentum tönkreteheti egy új fejlesztő első napját, és alááshatja a bizalmat. Futtassa a lépéseket saját maga tiszta környezetben.
Gyakori hibák
- A „miért” megszerzése az AI-hoz. A hamis indoklás rosszabb, mint az indoklás hiánya; A kód tulajdonosának meg kell írnia a tervezés okát.
- Nem ellenőrzi a telepítési lépéseket. A README, ami nem működik, lerombolja a bizalmat.
- A kódot ismétlő felesleges megjegyzés. Zajt termel, eltakarva a valódi „miért” értelmezéseket.
- Nem határozza meg a célközönséget. Az a dokumentum, amely nem világos, hogy kinek írták, nem használ sem a kezdő, sem a szakértő számára.
- A frissítés elválasztása a folyamattól. Ha a dokumentumot nem frissítik a kóddal, az gyorsan félrevezetővé válik.
Összefoglalva
Az AI leveszi a dokumentációból a mechanikai terhek nagy részét: gyors vázlatok README, docstring, API hivatkozás, változásnapló és PR-leírások. De nem tudhatja a "miért", ami a legértékesebb réteg, és veszélyes pótolni. A munkamegosztás egyértelmű: a mesterséges intelligencia előállítja a „mit/hogyan”, te hozzá a „miért”. Határozza meg a közönséget, biztosítson erőforrásokat, írjon elő struktúrát, jelölje meg az illeszkedő helyeket, és ellenőrizze az egyes telepítési lépéseket saját maga futtatásával. Tegye a dokumentációt a kódmódosítás szerves részévé.
Pályázati feladat
Válasszon egy modult vagy kis projektet, amelynek dokumentációja hiányzik vagy elavult. Először hozzon létre egy vázlatot az AI-ból a „strukturált README vázlat” (vagy docstring) sablonnal; Feltétlenül adja meg a forrást és a célközönséget. Ezután menjen végig minden olyan ponton, ahol a mesterséges intelligencia [VERIFY] vagy [MIÉRT SZÜKSÉGES] jelölést kapott: futtassa le a beállítási lépéseket, és saját tudásával töltse ki a tervezési „miért” részt. Jegyezze fel, hány lépést kell javítani, és hány „miért”-t adott hozzá.
ellenőrző lista
- [ ] A dokumentációban megkülönböztetem a "mit/hogyan" és a "miért" rétegeket.
- [ ] Nem én alkotom meg a „miért”-et a mesterséges intelligencia, hanem magam teszem hozzá.
- [ ] Megadom a promptnak a célközönséget és a tényleges forrásfájlokat.
- [ ] Az AI által megjelölt [VERIFY] pontokat személyesen végrehajtom.
- [ ] Megszüntetem a kódot ismétlő felesleges megjegyzéseket.
- [ ] A dokumentáció frissítését a kódmódosítás részévé teszem.