Fitimet:
- Aftësia për të prodhuar drafte README, docstring dhe changelog bazuar në audiencën e synuar dhe burimin me AI
- Aftësia për të ndarë shtresat "çfarë/si" dhe "pse" në dokumentacion dhe për të shtuar "pse" si njeri
- Verifikimi i hapave të instalimit duke i ekzekutuar personalisht dhe duke e bërë dokumentin pjesë të ndryshimit të kodit
Pjesa më e lënë pas dore, por më e qëndrueshme e softuerit është dokumentacioni. Kodi është i lexueshëm edhe pas muajsh; Ai që e ka shkruar është zhdukur, konteksti është harruar dhe ka mbetur vetëm ajo që është shkruar. Një README i mirë (dokument hyrës që shpjegon se çfarë është një projekt dhe si të instalohet dhe ekzekutohet), komentet e kodit shpjegues dhe një dokumentacion i përditësuar API (një referencë që shpjegon se si të përdoret një ndërfaqe) përcakton drejtpërdrejt shpejtësinë e një ekipi. Inteligjenca artificiale heq shumë nga "lodhja e të shkruarit" nga dokumentacioni - por ajo vjen me një kurth: AI mund të konkludojë nga kodi se çfarë bën, por shpesh nuk mund ta dijë pse është bërë në këtë mënyrë.
Në këtë njësi, do të mësoni se si të prodhoni README, komentin e kodit, vargun e dokumenteve (blloku i komenteve i shkruar për funksion/klasë), dokumentin API dhe regjistrin e ndryshimit me AI; dhe si të ruhet në mënyrë njerëzore pjesa më e vlefshme e dokumentacionit: "pse".
Dallimi midis "Çfarë" dhe "Pse"
Ka dy shtresa dokumentacioni. E para është çfarë/si: "ky funksion rendit një listë", "ekzekuto këtë komandë për të instaluar". Këto mund të nxirren nga kodi dhe struktura; AI shkëlqen këtu. Së dyti, pse: "pse e bëmë këtë shërbim asinkron dhe jo sinkron", "pse kjo vlerë kufitare është 30 sekonda", "pse zgjodhëm këtë bibliotekë mbi tjetrën". Këto nuk janë të shkruara në kod; Është produkt i vendimeve të projektimit, kufizimeve dhe dhimbjes së kaluar.
AI nuk e di "pse"; Në rastin më të mirë, ajo krijon një supozim të arsyeshëm - gjë që është e rrezikshme, sepse një arsye e gabuar është më e keqe se pa arsye. Pra, ndarja e punës është e qartë: AI harton "çfarë/si", ju shtoni "pse". Komenti më i vlefshëm është ai që thotë atë që kodi nuk mund të thotë.
Këshillë: Mos e përsëritni me koment atë që thotë qartë vetë kodi (si i = i + 1 // rrit i me një). AI ndonjëherë prodhon komente të tilla të tepërta; Eliminojini ato dhe kushtojini energjinë tuaj komenteve “pse”.
Hap pas hapi: Gjenerimi i dokumentacionit me AI
- Specifikoni audiencën e synuar. "Një zhvillues që sapo ka filluar", "ekipi i jashtëm që do të përdorë këtë API", "unë i ardhshëm" - audienca vendos tonin për gjuhën dhe thellësinë.
- Jepni burimin. Shtoni kodin përkatës, README ekzistues, shembullin e përdorimit në prompt. Një dokument pa burim është një ftesë për fabrikim.
- Struktura e imponimit. Seksionet standarde për README (Qëllimi, Instalimi, Përdorimi, Konfigurimi, Kontributi), formati i projektit për docstring.
- Shënoni hapësirat "pse". Kërkojini AI të shënojë vendimet për të cilat nuk e njeh arsyetimin si "kërkohet një shënim 'pse' këtu"; Pastaj ju plotësoni ato boshllëqe.
- Verifiko. Kryeni në fakt hapat e instalimit; provoni kodin e mostrës. Një README që nuk funksionon është më keq se mos README fare.
Tre Mini Rastet
Rasti 1 - README përshpejtoi hyrjen në bord. Mungonte README e një mjeti me burim të hapur; Kontribuesit e rinj luftuan me instalimin për një mesatare prej 2 orësh. Ekipi ia dha AI skriptet e instalimit dhe paketën.json dhe hartoi një README të strukturuar, më pas i drejtoi vetë hapat në një makinë të pastër dhe shtoi dy varësitë që mungonin. Koha e instalimit për kontribuuesit e mëvonshëm u ul në një mesatare prej 25 minutash.
Rasti 2 - Kurthi i krijuar "pse". Një zhvillues i kërkoi AI-së një koment pranë një vlere të skadimit (timeout=30). AI shkroi një justifikim të arsyeshëm por të pasaktë "për të toleruar vonesë të lartë të rrjetit"; arsyeja e vërtetë ishte kufiri kontraktual prej 30 sekondash i një shërbimi në rrjedhën e poshtme. Keqinterpretimi bëri që një zhvillues i mëvonshëm të rriste në mënyrë të panevojshme vlerën, duke çuar në një incident. Mësimi: pronari i kodit duhet të verifikojë justifikimin.
Rasti 3 — Standardi Docstring është bërë i automatizuar. Një modul ndihmës me 40 funksione nuk kishte vargje dokumentesh. UA-së iu dha formati i projektit (stili i Google) dhe prodhoi përshkrime të parametrave, kthimit dhe përjashtimeve për secilin funksion; Zhvilluesi i rishikoi këto dhe rregulloi disa deklarata të llojit të pasaktë. Dokumentimi i 40 funksioneve u zvogëlua nga rreth gjysmë dite në një orë.
Katër modele të kopjueshme
Drafti i strukturuar i README:
Audienca e synuar: {{ p.sh. kontribuues i ri}}. Shkruani një draft README bazuar në skedarët e mëposhtëm. Seksionet: Qëllimi, Karakteristikat, Kërkesat, Instalimi, Funksionimi, Konfigurimi, Testimi, Kontributi. Nxjerrja e komandave të instalimit/ ekzekutimit nga skedarët aktualë; MOSTUES. Shënoni vendet për të cilat nuk jeni të sigurt me "[VERIFY]". Burimi: {{package.json / skriptet / kodi i mostrës}}
Referenca e Docstring/API:
Shkruani vargun e dokumenteve për këto funksione në formatin {{stili i projektit: Google/NumPy/JSDoc}}: përmbledhje e shkurtër, parametrat (lloji + kuptimi), kthimi, përjashtimet e hedhura, 1 shembull i shkurtër. Mos e përsëritni atë që kodi thotë QARTË. Shënoni vendimet e projektimit që kërkojnë "pse" si "[PSE E NEVOJSHME]", mos shkruani një justifikim të sajuar.{{code}}
Hiq hapësirat për komentin "pse":
Në këtë kod, zhvilluesi i ardhshëm mund të pyesë "pse është kështu?" (numra magjikë, vendime të pazakonta, zgjidhje). Jep një koment SKELETI për secilin, por arsyetimin e lë BASHKË; Unë do të plotësoj justifikimin.{{kodi}}
Deklarata e ndryshimeve/PR:
Shkruani një {{ hyrje të ndryshimeve / përshkrim PR}} nga ndryshimi i mëposhtëm. Formati: Çfarë ka ndryshuar (në gjuhën e përdoruesit), Pse (çështja: {{...}}), Ndryshimi i thyer (nëse ka), A është testuar. Rregullo zhargonin teknik për audiencën e synuar.{{ndryshime}}
Prompt i dobët / Prompt i fortë
E dobët: "Shkruani një README për këtë projekt."
I fortë: "Audienca e synuar: një zhvillues që klonon këtë depo për herë të parë. Bazuar në paketën e bashkangjitur.json, docker-compose.yml dhe dosjen scripts/, shkruani një draft README me seksionet Qëllimi, Kërkesat, Instalimi, Operacioni, Testimi, Kontributi. Ekstraktoni komandat nga këto skedarë; VERË mos shënoni ndonjë skedar."
Versioni i fortë i jep audiencës, burimin, strukturën dhe rregullin "bëje, shënoje"; në mënyrë që dokumenti të bazohet në dosje reale dhe të duken qartë vendet që do të verifikohen.
Lloji i dokumentit
AI bën mirë
Human shton/verifikon
Instalimi i README
përvijimi i hapit
Drejtoni hapat dhe konfirmoni
Docstring/API
Struktura, parametri, lloji
Lloji i saktë dhe "pse"
Komenti i kodit
Përmbledhje "Çfarë po bën".
“Pse është ky” justifikimi
Ndryshim/PR
drafti i parë
Ndikimi dhe saktësia
Vendimi arkitektonik (ADR)
skelet
Vendime reale dhe kompromise
Dokumentacioni kërkon mirëmbajtje
Aspekti më i rrezikshëm i një dokumenti është kur ai duket i vërtetë edhe pse është i rremë. Kur kodi ndryshon dhe dokumenti nuk përditësohet, ai mashtron në mënyrë aktive lexuesin. Inteligjenca artificiale e bën përditësimin të lehtë: lëshoni një ndryshim dhe pyesni "në cilat pjesë të dokumentit ndikon ky ndryshim?" ju mund të pyesni. Por është procesi që siguron përditësimin - bëjeni përditësimin e dokumentacionit pjesë të ndryshimit të kodit (kriteri i pranimit të PR). AI përshpejtohet; Ekipi ndërton disiplinë.
Kujdes: Mos publikoni pa verifikuar hapat e instalimit në një README. Një dokument "ndoshta punë" mund të prishë ditën e parë të një zhvilluesi të ri dhe të gërryejë besimin. Drejtoni hapat vetë në një mjedis të pastër.
Gabimet e zakonshme
- Marrja e "pse" për t'iu përshtatur AI. Justifikimi i rremë është më i keq se mos justifikimi; Pronari i kodit duhet të shkruajë arsyen e dizajnit.
- Nuk verifikohen hapat e instalimit. LEXONI që nuk funksionon shkatërron besimin.
- Koment i panevojshëm që përsërit kodin. Ajo prodhon zhurmë, duke errësuar interpretimet e vërteta "pse".
- Duke mos specifikuar audiencën e synuar. Një dokument që është i paqartë se kujt i është shkruar nuk ka asnjë dobi as për fillestarin dhe as për ekspertin.
- Ndarja e përditësimit nga procesi. Nëse dokumenti nuk përditësohet me kodin, ai shpejt bëhet mashtrues.
Në përmbledhje
Inteligjenca artificiale heq shumë nga barra mekanike e dokumentacionit: hartime të shpejta README, varg docstring, referencë API, ndryshime dhe përshkrime PR. Por ajo nuk mund të dijë "pse", e cila është shtresa më e vlefshme, dhe është e rrezikshme për ta përbërë atë. Ndarja e punës është e qartë: AI prodhon "çfarë/si", ju shtoni "pse". Specifikoni audiencën, siguroni burime, impononi strukturën, shënoni vendet që përshtaten dhe verifikoni çdo hap instalimi duke e ekzekutuar vetë. Bëjeni dokumentacionin një pjesë integrale të ndryshimit të kodit.
Detyra e aplikimit
Zgjidhni një modul ose projekt të vogël, dokumentacioni i të cilit mungon ose është i vjetëruar. Fillimisht gjeneroni një skicë nga AI me shabllonin "draft i strukturuar README" (ose varg dokumentesh); Sigurohuni që të jepni burimin dhe audiencën e synuar. Më pas kaloni nëpër secilën pikë ku AI ka shënuar [VERIFY] ose [PSE NEVOJSHME]: në fakt ekzekutoni hapat e konfigurimit dhe plotësoni dizajnin "pse" me njohuritë tuaja. Vini re se sa hapa duhet të rregullohen dhe sa "pse" keni shtuar.
listë kontrolli
- [ ] Në dokumentacion dalloj shtresat "çfarë/si" dhe "pse".
- [ ] Unë nuk e bëj që AI të krijojë "pse", e shtoj vetë.
- [ ] Unë i jap kërkesës audiencën e synuar dhe skedarët burimor aktual.
- [ ] Unë verifikoj pikat [VERIFY] të shënuara nga AI duke i ekzekutuar ato personalisht.
- [ ] Unë eliminoj komentet e panevojshme që përsërisin kodin.
- [ ] Po e bëj përditësimin e dokumentacionit pjesë të ndryshimit të kodit.