Dobici:
- Sposobnost izrade nacrta README, docstringa i dnevnika promjena na osnovu ciljne publike i izvora sa AI
- Sposobnost odvajanja slojeva 'šta/kako' i 'zašto' u dokumentaciji i dodavanje 'zašto' kao čovjek
- Provjera koraka instalacije tako što ćete ih lično pokrenuti i učiniti dokument dijelom promjene koda
Najčešći zanemareni, ali najdugotrajniji dio softvera je dokumentacija. Kod je čitljiv čak i nakon nekoliko mjeseci; Osoba koja je to napisala je nestala, kontekst je zaboravljen, a ostalo je samo ono što je napisano. Dobar README (uvodni dokument koji objašnjava šta je projekat i kako ga instalirati i pokrenuti), komentari koda sa objašnjenjima i ažurna API dokumentacija (referenca koja objašnjava kako se koristi interfejs) direktno određuje brzinu tima. AI uklanja mnogo "zamora od pisanja" iz dokumentacije - ali dolazi sa zamkom: AI može zaključiti iz koda šta radi, ali često ne može znati zašto se to radi na taj način.
U ovoj jedinici ćete naučiti kako da napravite README, komentar koda, docstring (blok komentara napisan po funkciji/klasi), API dokument i dnevnik promjena sa AI; i kako ljudski sačuvati najvredniji dio dokumentacije: „zašto“.
Razlika između "šta" i "zašto"
Postoje dva sloja dokumentacije. Prvi je šta/kako: "ova funkcija sortira listu", "pokrenite ovu naredbu za instalaciju". Oni se mogu izdvojiti iz koda i strukture; AI se ovdje ističe. Drugo, zašto: "zašto smo ovu uslugu učinili asinhronom, a ne sinhronom", "zašto je ova granična vrijednost 30 sekundi", "zašto smo odabrali ovu biblioteku u odnosu na drugu". Ovo nije napisano u kodu; To je proizvod dizajnerskih odluka, ograničenja i prošlih bolova.
AI ne zna "zašto"; U najboljem slučaju, to čini razumno nagađanje - što je opasno, jer je pogrešan razlog gori od nikakvog razloga. Dakle, podjela rada je jasna: AI sastavlja "šta/kako", vi dodajete "zašto". Najvredniji komentar je onaj koji kaže ono što kod ne može reći.
Savjet: Ne ponavljajte s komentarom ono što sam kod jasno kaže (kao i = i + 1 // povećajte i za jedan). AI ponekad proizvodi takve suvišne komentare; Eliminišite ih i posvetite svoju energiju komentarima „zašto“.
Korak po korak: generiranje dokumentacije pomoću AI
- Odredite ciljnu publiku. „Programer koji tek počinje“, „eksterni tim koji će koristiti ovaj API“, „ja budućnost“ — publika postavlja ton za jezik i dubinu.
- Dajte izvor. Dodajte odgovarajući kod, postojeći README, primjer upotrebe u prompt. Dokument bez izvora je poziv na izradu.
- Struktura nametanja. Standardne sekcije za README (Svrha, Instalacija, Upotreba, Konfiguracija, Doprinos), format projekta za docstring.
- Označite "zašto" razmake. Zamolite AI da označi odluke za koje ne zna obrazloženje kao "ovdje je potrebna napomena 'zašto'"; Zatim popunite te praznine.
- Verify. Zapravo pokrenite korake instalacije; isprobajte uzorak koda. README koji ne radi je gori od toga da uopšte nema README-a.
Tri mini futrole
Slučaj 1 — README ubrzano uključivanje. Nedostajao je README alata otvorenog koda; Novi saradnici su se mučili sa instalacijom u prosjeku 2 sata. Tim je dao instalacione skripte i package.json AI-u i izradio strukturirani README, a zatim je pokrenuo same korake na čistoj mašini i dodao dvije nedostajuće zavisnosti. Vrijeme instalacije za sljedeće saradnike smanjeno je na prosječno 25 minuta.
Slučaj 2 — Izmišljena zamka „zašto“. Programer je od AI tražio komentar pored vrijednosti vremenskog ograničenja (timeout=30). AI je napisao razumno, ali netačno opravdanje "za toleriranje velikog kašnjenja mreže"; pravi razlog je bilo ugovorno ograničenje od 30 sekundi nizvodne usluge. Pogrešna interpretacija navela je naknadnog programera da nepotrebno poveća vrijednost, što je dovelo do incidenta. Pouka: vlasnik koda mora provjeriti opravdanost.
Slučaj 3 — Docstring standard je postao automatizovan. Pomoćni modul sa 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 netačnih deklaracija tipa. Dokumentiranje 40 funkcija smanjeno je sa otprilike pola dana na sat vremena.
Četiri predloška koji se mogu kopirati
Strukturirani README nacrt:
Ciljna publika: {{npr. novi saradnik}}. Napišite nacrt README-a na osnovu datoteka ispod. Odjeljci: Svrha, Karakteristike, Zahtjevi, Instalacija, Rad, Konfiguracija, Testiranje, Doprinos. Izdvojite komande za instalaciju/pokretanje iz stvarnih datoteka; FITTING. Označite mjesta za koja niste sigurni sa "[VERIFY]". Izvor: {{package.json / scripts / sample code}}
Docstring/API referenca:
Napišite docstring ovim funkcijama u formatu {{project style: Google/NumPy/JSDoc}}: kratak sažetak, parametri (tip + značenje), povratak, izbačeni izuzeci, 1 kratak primjer. Nemojte ponavljati ono što kod JASNO kaže. Označite odluke o dizajnu koje zahtijevaju "zašto" kao "[ZAŠTO POTREBNO]", nemojte pisati izmišljeno opravdanje.{{code}}
Uklonite razmake za komentar "zašto":
U ovom kodu, sljedeći programer bi mogao pitati "zašto je to tako?" (magični brojevi, neobične odluke, zaobilazna rješenja). Dajte komentar SKELETON za svaki, ali ostavite obrazloženje PRAZNO; Popunit ću opravdanje.{{code}}
Dnevnik promjena/PR izjava:
Napišite {{unos u dnevniku promjena / PR opis}} iz razlike ispod. Format: Šta se promijenilo (na korisničkom jeziku), Zašto (problem: {{...}}), Prekidna promjena (ako postoji), Da li je testirano. Prilagodite tehnički žargon ciljanoj publici.{{diff}}
Slaba prompt / Jaka prompt
Slabo: "Napišite README za ovaj projekat."
Snažno: "Ciljna publika: programer koji klonira ovaj repo po prvi put. Na osnovu priloženog package.json, docker-compose.yml i scripts/ foldera, napišite nacrt README-a sa odjeljcima Svrha, Zahtjevi, Instalacija, Operacija, Testiranje, Doprinos. Izvucite komande iz ovih datoteka, nemojte ih izmišljati; označite bilo gdje AKO niste sigurni."
Jaka verzija daje publiku, izvor, strukturu i pravilo „napravi, označi“; tako da je dokument zasnovan na stvarnim fajlovima i da su mesta koja se verificiraju jasno vidljiva.
Vrsta dokumenta
AI radi dobro
Ljudski dodaje/verifikuje
README instalacija
nacrt koraka
Pokrenite korake i potvrdite
Docstring/API
Struktura, parametar, tip
Ispravan tip i "zašto"
Komentar koda
Sažetak "Šta radi".
"Zašto je ovo" opravdanje
Dnevnik promjena/PR
prvi nacrt
Uticaj i tačnost
Arhitektonska odluka (ADR)
skelet
Prave odluke i kompromisi
Dokumentacija zahtijeva održavanje
Najopasniji aspekt dokumenta je kada se čini istinitim iako je lažan. Kada se kod promijeni, a dokument se ne ažurira, on aktivno obmanjuje čitaoca. AI olakšava ažuriranje: izdajte diff i pitajte "na koje dijelove dokumenta utiče ova promjena?" možete pitati. Ali to je proces koji osigurava ažurnost — neka ažuriranje dokumentacije bude dio promjene koda (kriterijum prihvatanja PR-a). AI ubrzava; Tim gradi disciplinu.
Oprez: Nemojte objavljivati bez provjere koraka instalacije u README. Dokument "vjerovatno radi" može uništiti prvi dan novog programera i narušiti povjerenje. Pokrenite korake sami u čistom okruženju.
Uobičajene greške
- Dobijanje „zašto“ da odgovara AI. Lažno opravdanje je gore od neopravdanja; Vlasnik koda treba da napiše razlog dizajna.
- Ne provjeravamo korake instalacije. README koji ne radi uništava povjerenje.
- Nepotreban komentar koji ponavlja kod. Proizvodi buku, prikrivajući stvarna tumačenja "zašto".
- Ne navodeći ciljnu publiku. Dokument za koji nije jasno kome je napisan nije od 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 veliki dio mehaničkog tereta iz dokumentacije: brzi nacrti README, docstring, API reference, dnevnik promjena i PR opisi. Ali ne može znati "zašto", koji je najvredniji sloj, i opasno ga je nadoknaditi. Podjela rada je jasna: AI proizvodi "šta/kako", vi dodajete "zašto". Odredite publiku, osigurajte resurse, nametnite strukturu, označite mjesta koja će odgovarati i provjerite svaki korak instalacije tako što ćete ga sami pokrenuti. Učinite dokumentaciju sastavnim dijelom promjene koda.
Zadatak aplikacije
Odaberite modul ili mali projekat čija dokumentacija nedostaje ili je zastarjela. Prvo generirajte nacrt iz AI sa šablonom “strukturirani README nacrt” (ili docstring); Obavezno navedite izvor i ciljnu publiku. Zatim prođite kroz svaku tačku gdje je AI označio [VERIFY] ili [ZAŠTO TREBA]: zapravo pokrenite korake podešavanja i popunite dizajn „zašto“ svojim znanjem. Zabilježite koliko koraka treba popraviti i koliko „zašto“ ste dodali.
kontrolna lista
- [ ] U dokumentaciji razlikujem slojeve "šta/kako" i "zašto".
- [ ] Ne činim da AI izmišlja "zašto", ja to sam dodajem.
- [ ] Dajem upitu ciljnu publiku i stvarne izvorne datoteke.
- [ ] Provjeravam [VERIFY] tačke koje je označila AI tako što ih lično izvršavam.
- [ ] Uklanjam nepotrebne komentare koji ponavljaju kod.
- [ ] Ažuriranje dokumentacije činim dijelom promjene koda.