Dobici:
- Sposobnost izrade README-a, docstring-a i skica dnevnika promjena na temelju ciljane publike i izvora s umjetnom inteligencijom
- Sposobnost odvajanja slojeva 'što/kako' i 'zašto' u dokumentaciji i dodavanje 'zašto' kao čovjeka
- Provjera instalacijskih koraka tako što ćete ih osobno pokrenuti i učiniti dokument dijelom promjene koda
Najčešće zanemaren, ali najdugovječniji dio softvera je dokumentacija. Kod je čitljiv čak i nakon nekoliko mjeseci; Onog koji je to napisao više nema, kontekst se zaboravlja, a ostaje samo ono što je napisano. Dobar README (uvodni dokument koji objašnjava što je projekt i kako ga instalirati i pokrenuti), objašnjenja komentara koda i ažurna API dokumentacija (referenca koja objašnjava kako koristiti sučelje) izravno određuje brzinu tima. Umjetna inteligencija uklanja dosta "umora od pisanja" dokumentacije — ali dolazi sa zamkom: AI može zaključiti iz koda što radi, ali često ne može znati zašto je to učinjeno na taj način.
U ovoj jedinici naučit ćete kako izraditi README, komentar koda, docstring (blok komentara napisan po funkciji/klasi), API dokument i dnevnik promjena s AI; i kako ljudski sačuvati najvrjedniji dio dokumentacije: "zašto".
Razlika između "Što" i "Zašto"
Postoje dva sloja dokumentacije. Prvi je što/kako: "ova funkcija sortira popis", "pokreni ovu naredbu za instalaciju". Oni se mogu izdvojiti iz koda i strukture; AI ovdje briljira. Drugo, zašto: "zašto smo ovu uslugu učinili asinkronom, a ne sinkronom", "zašto je ova granična vrijednost 30 sekundi", "zašto smo odabrali ovu biblioteku umjesto ostalih". Oni nisu napisani u kodu; To je proizvod dizajnerskih odluka, ograničenja i boli iz prošlosti.
AI ne zna "zašto"; U najboljem slučaju, čini razumnu pretpostavku - što je opasno, jer je pogrešan razlog gori od nepostojanja razloga. Dakle, podjela rada je jasna: umjetna inteligencija nacrtuje "što/kako", vi dodajete "zašto". Najvrjedniji komentar je onaj koji govori ono što kodeks ne može reći.
Savjet: Nemojte u komentaru ponavljati ono što sam kod jasno kaže (kao i = i + 1 // povećajte i za jedan). AI ponekad proizvodi takve suvišne komentare; Eliminirajte ih i posvetite svoju energiju komentarima "zašto".
Korak po korak: Generiranje dokumentacije pomoću umjetne inteligencije
- Navedite ciljanu publiku. "Programer koji tek počinje", "vanjski tim koji će koristiti ovaj API", "budući ja" - publika daje ton jeziku i dubini.
- Daj izvor. Dodajte relevantni kod, postojeći README, primjer upotrebe u upit. Dokument bez izvora je poziv na izmišljanje.
- Struktura nametanja. Standardni odjeljci za README (svrha, instalacija, upotreba, konfiguracija, doprinos), format projekta za niz dokumenata.
- Označite razmake "zašto". Zamolite AI da označi odluke za koje ne zna obrazloženje kao "ovdje je potrebna bilješka 'zašto'"; Zatim ispunite te praznine.
- Potvrdi. Zapravo pokrenite korake instalacije; isprobajte primjer koda. README koji ne radi je gori od nikakvog README-a.
Tri mini kućišta
Slučaj 1 — README ubrzana integracija. Nedostajao je README alata otvorenog koda; Novi suradnici borili su se s instalacijom u prosjeku 2 sata. Tim je dao instalacijske skripte i package.json AI-u i napravio nacrt strukturiranog README-a, zatim sam pokrenuo korake na čistom stroju i dodao dvije nedostajuće ovisnosti. Vrijeme instalacije za sljedeće suradnike smanjeno je na prosječnih 25 minuta.
Slučaj 2 — Izmišljena zamka "zašto". Programer je od umjetne inteligencije zatražio komentar uz vrijednost isteka (timeout=30). AI je napisao razumno, ali netočno obrazloženje "tolerirati visoko kašnjenje mreže"; pravi razlog bilo je ugovorno ograničenje od 30 sekundi nizvodne usluge. Pogrešno tumačenje navelo je kasnijeg programera da nepotrebno poveća vrijednost, što je dovelo do incidenta. Lekcija: vlasnik koda mora provjeriti opravdanje.
Slučaj 3 — Standard Docstring postao je automatiziran. Pomoćni modul s 40 funkcija nije imao nizove dokumenata. AI je dobio format projekta (Google stil) i proizveo opise parametara, povrata i izuzetaka za svaku funkciju; Programer ih je pregledao i popravio nekoliko netočnih deklaracija tipa. Dokumentiranje 40 funkcija smanjilo se s otprilike pola dana na sat vremena.
Četiri predloška za kopiranje
Strukturirani nacrt README:
Ciljana publika: {{npr. novi suradnik}}. Napišite nacrt README-a na temelju datoteka u nastavku. Odjeljci: Svrha, Značajke, Zahtjevi, Instalacija, Rad, Konfiguracija, Testiranje, Doprinos. Ekstrakt instalacijskih/pokretačkih naredbi iz stvarnih datoteka; UKLJUČIVANJE. Označite mjesta za koja niste sigurni s "[VERIFY]". Izvor: {{package.json / skripte / uzorak koda}}
Docstring/API referenca:
Napišite niz dokumenata za ove funkcije u formatu {{project style: Google/NumPy/JSDoc}}: kratki sažetak, parametri (tip + značenje), povratak, izbačene iznimke, 1 kratki primjer. Nemojte ponavljati ono što kodeks JASNO kaže. Označite dizajnerske odluke koje zahtijevaju "zašto" kao "[ZAŠTO JE POTREBNO]", nemojte pisati izmišljeno obrazloženje.{{code}}
Uklonite razmake za komentar "zašto":
U ovom kodu bi sljedeći programer mogao pitati "zašto je to tako?" (magični brojevi, neobične odluke, zaobilazna rješenja). Dajte komentar KOSTUR za svaki, ali ostavite PRAZNO obrazloženje; Ispunit ću obrazloženje.{{code}}
Dnevnik promjena/PR izjava:
Napišite {{unos u dnevnik promjena / PR opis}} iz razlike ispod. Format: Što se promijenilo (na jeziku korisnika), Zašto (problem: {{...}}), Prijelomna promjena (ako postoji), Je li testirano. Prilagodite tehnički žargon ciljanoj publici.{{diff}}
Slab upit / Jak upit
Slabo: "Napišite README za ovaj projekt."
Jaka: "Ciljna publika: programer koji prvi put klonira ovaj repo. Na temelju priloženog package.json, docker-compose.yml i mape scripts/, napišite nacrt README-a s odjeljcima Svrha, Zahtjevi, Instalacija, Operacija, Testiranje, Doprinos. Izdvojite naredbe iz ovih datoteka, nemojte ih izmišljati; označite gdje god niste sigurni s [VERIFY]."
Jaka verzija daje publiku, izvor, strukturu i pravilo "napravi, označi"; tako da se dokument temelji na stvarnim datotekama i da su mjesta koja treba provjeriti jasno vidljiva.
Vrsta dokumenta
AI se dobro snalazi
Čovjek dodaje/provjerava
README instalacija
obris koraka
Pokrenite korake i potvrdite
Docstring/API
Struktura, parametar, tip
Ispravan tip i "zašto"
Komentar koda
Sažetak "Što on radi".
"Zašto je to" opravdanje
Dnevnik promjena/PR
prvi nacrt
Utjecaj i točnost
Arhitektonska odluka (ADR)
kostur
Prave odluke i kompromisi
Dokumentacija zahtijeva održavanje
Najopasniji aspekt dokumenta je kada se čini istinitim iako je lažan. Kada se kôd promijeni, a dokument nije ažuriran, on aktivno dovodi čitatelja u zabludu. AI olakšava ažuriranje: izdajte diff i pitajte "na koje dijelove dokumenta ova promjena utječe?" možete pitati. Ali proces je taj koji osigurava ažurnost — neka ažuriranje dokumentacije bude dio promjene koda (PR-ov kriterij prihvaćanja). AI ubrzava; Tim gradi disciplinu.
Oprez: Nemojte objavljivati bez provjere koraka instalacije u README-u. Dokument koji "vjerojatno radi" može upropastiti prvi dan novog programera i narušiti povjerenje. Sami trčite korake u čistom okruženju.
Uobičajene greške
- Dobivanje "zašto" za uklapanje u AI. Lažno opravdanje je gore od nikakvog opravdanja; Vlasnik koda trebao bi napisati razlog dizajna.
- Ne provjeravam korake instalacije. README koji ne radi uništava povjerenje.
- Bespotreban komentar ponavljanja koda. Proizvodi buku, prikrivajući prave interpretacije "zašto".
- Ne navodeći ciljanu publiku. Dokument koji je nejasno kome je napisan ne koristi ni početniku ni stručnjaku.
- Odvajanje ažuriranja od procesa. Ako dokument nije ažuriran kodom, brzo postaje pogrešan.
Ukratko
AI preuzima velik dio mehaničkog tereta dokumentacije: brzi nacrti README, niz dokumenata, API referenca, zapis promjena i PR opisi. Ali ne može znati "zašto", što je najvrjedniji sloj, i opasno ga je izmisliti. Podjela rada je jasna: umjetna inteligencija proizvodi "što/kako", a vi dodajete "zašto". Odredite publiku, osigurajte resurse, nametnite strukturu, označite mjesta koja odgovaraju i provjerite svaki korak instalacije tako što ćete ga pokrenuti sami. Neka dokumentacija bude sastavni dio promjene koda.
Zadatak aplikacije
Odaberite modul ili mali projekt čija dokumentacija nedostaje ili je zastarjela. Najprije generirajte nacrt iz AI s predloškom "strukturiranog README nacrta" (ili niza dokumenata); Svakako navedite izvor i ciljanu publiku. Zatim prođite kroz svaku točku gdje je AI označio [VERIFY] ili [WHY NEEDED]: zapravo pokrenite korake postavljanja i ispunite dizajn "zašto" svojim znanjem. Zabilježite koliko koraka treba popraviti i koliko "zašto" ste dodali.
popis za provjeru
- [ ] U dokumentaciji razlikujem slojeve "što/kako" i "zašto".
- [ ] Ne tjeram umjetnu inteligenciju da smisli "zašto", ja to sam dodajem.
- [ ] Dajem upit ciljanoj publici i stvarnim izvornim datotekama.
- [ ] Provjeravam [VERIFY] točke koje je označio AI tako što ih osobno izvršavam.
- [ ] Eliminiram nepotrebne komentare koji ponavljaju kod.
- [ ] Ažuriranje dokumentacije čini dijelom promjene koda.