Girdeji:
- AI bilen maksatly diňleýjä we çeşmä esaslanýan README, docstring we changelog garalamalaryny öndürmek ukyby
- Resminamalarda 'näme / nädip' we 'näme üçin' gatlaklaryny bölüp bilmek we adam hökmünde 'näme üçin' goşmak ukyby
- Gurmak ädimlerini şahsy işlemek we resminamany kod üýtgetmesiniň bir bölegi etmek
Programma üpjünçiliginiň iň ýygy-ýygydan äsgerilmeýän, ýöne iň uzak dowam edýän bölegi resminamalardyr. Kod birnäçe aýdan soň hem okalýar; Ony ýazan adam ýitdi, kontekst ýatdan çykaryldy we diňe ýazylanlar galypdy. Gowy README (taslamanyň nämedigini we ony nädip gurmalydygyny we işlemelidigini düşündirýän giriş resminamasy), düşündiriş kody düşündirişleri we iň täze API resminamalary (interfeýsi nähili ulanmalydygyny düşündirýän salgylanma) toparyň tizligini gönüden-göni kesgitleýär. AI resminamalardan “ýazuw ýadawlygyny” köp alýar - ýöne duzak bilen gelýär: AI näme edýändigini koddan alyp biler, ýöne näme üçin beýle edilendigini köplenç bilmez.
Bu bölümde, README, kod düşündirişi, dokument (funksiýa / synp üçin ýazylan teswir bloky), API resminamasy we AI bilen üýtgeşme öndürmegi öwrenersiňiz; we resminamalaryň iň gymmatly bölegini nädip gorap saklamaly: "näme üçin".
"Näme" bilen "Näme üçin" arasyndaky tapawut?
Iki gat resminama bar. Birinjisi näme / nädip: "bu funksiýa sanawy tertipleýär", "gurmak üçin buýrugy işlediň". Bulary koddan we gurluşdan alyp bolýar; AI bu ýerde ýokary. Ikinjiden, näme üçin: "näme üçin bu hyzmaty sinhron däl-de, asynkron etdik", "bu çäklendirmäniň bahasy 30 sekunt", "näme üçin bu kitaphanany beýlekisinden saýladyk". Bular kodda ýazylmandyr; Dizaýn kararlarynyň, çäklendirmeleriň we geçmişdäki agyrynyň önümidir.
AI "näme üçin" bilenok; Iň gowusy, bu dogry bir çaklamany düzýär - bu howply, sebäbi nädogry sebäp asla ýok. Şonuň üçin zähmet bölünişi düşnüklidir: AI “näme / nädip” düzýär, “näme üçin” goşýarsyňyz. Iň gymmatly teswir, koduň aýdyp bilmeýän zadyny aýdýar.
Maslahat: Kodyň özi aýdyň aýdýanlaryny teswir bilen gaýtalamaň (i = i + 1 // i-ni köpeltmek ýaly). AI käwagt şeýle artykmaç teswirleri çykarýar; Olary ýok ediň we güýjüňizi “näme üçin” teswirlere sarp ediň.
Stepdimme-ädim: AI bilen resminamalaşdyrmak
- Maksatly diňleýjini görkeziň. “Täze döredilen bir dörediji”, “bu API ulanjak daşarky topar”, “geljekki men” - tomaşaçylar dil we çuňluk äheňini düzýärler.
- Çeşmesini beriň. Degişli kody, bar bolan README, mysal üçin ulanylyşy goşuň. Düzedilmedik resminama, toslama çakylykdyr.
- Goýma gurluşy. README (Maksat, gurnama, ulanyş, konfigurasiýa, goşant) üçin standart bölümler, dokumentler üçin taslama formaty.
- "Näme üçin" boşluklary belläň. AI-den esaslaryny bilmeýän kararlaryny "bu ýerde" näme üçin "bellik gerek" diýip bellemegini soraň; Soň bolsa şol boş ýerleri doldurarsyňyz.
- Barlaň. Aslynda gurnama ädimlerini işlediň; nusga koduny synap görüň. Işlemeýän README asla README ýok.
Üç kiçi waka
1-nji hadysa - Gämide README çaltlaşdyryldy. Açyk çeşme guralynyň README ýitdi; Täze goşant goşanlar ortaça 2 sagat gurnamak bilen göreşdiler. Topar gurnama skriptlerini we package.json-y AI-e berdi we düzülen README taýýarlady, soň basgançaklary arassa maşyna geçirdi we ýiten iki garaşlylygy goşdy. Ondan soňky goşant goşanlar üçin gurnama wagty ortaça 25 minuta çenli azaldy.
2-nji waka - “Näme üçin” duzak. Bir dörediji AI-den gutarýan bahanyň (wagt gutarmagy = 30) gapdalynda düşündiriş sorady. AI "ýokary ulgamyň gijä galmagyna çydamly" esasly, ýöne nädogry delil ýazdy; asyl sebäbi aşaky hyzmatyň şertnamalaýyn 30 sekuntlyk çägi boldy. Nädogry düşündiriş, indiki işläp düzüjiniň gereksiz bahany ýokarlandyrmagyna sebäp boldy we bir hadysa sebäp boldy. Sapak: kod eýesi esaslandyrmany barlamaly.
3-nji hadysa - “Docstring” standarty awtomatlaşdyryldy. 40 funksiýaly kömekçi modulyň dokumentleri ýokdy. AI-e taslama formaty (Google stili) berildi we her funksiýa üçin parametr, gaýdyp geliş we kadadan çykma beýany öndürildi; Öndüriji bulary gözden geçirdi we birnäçe nädogry görnüşli beýannamalary düzeddi. 40 funksiýany resminamalaşdyrmak ýarym günden bir sagada çenli azaldy.
Göçürip boljak dört şablon
Düzülen README taslamasy:
Maksatly diňleýjiler: {{meselem täze goşantçy}} Aşakdaky faýllaryň esasynda README taslamasyny ýazyň. Bölümler: Maksat, aýratynlyklar, talaplar, gurnamak, işlemek, konfigurasiýa, synag, goşant. Hakyky faýllardan gurnamak / işletmek buýruklaryny çykarmak; FITTING. Ynanmaýan ýerleriňizi "[VERIFY]" bilen belläň. Çeşme: {{package.json / skriptler / nusga kody}}
Docstring / API salgylanmasy:
Funksiýa stilinde bu funksiýalara dokument ýazyň: Google / NumPy / JSDoc}} formatda: gysgaça mazmun, parametrler (görnüş + many), gaýdyp gelmek, atylan kadadan çykmalar, 1 gysga mysal. Koduň aýdyň diýýänini gaýtalamaň. "Näme üçin" talap edýän dizaýn kararlaryny "[Näme üçin GEREK]" diýip belläň, toslanan delil ýazmaň. {{Kod}}
"Näme üçin" düşündiriş üçin boş ýerleri aýyryň:
Bu kodda indiki dörediji "näme üçin beýle?" Diýip sorap biler. (jadyly sanlar, üýtgeşik kararlar, çözgütler). Her biri üçin SKELETON düşündiriş beriň, ýöne BLANK esaslandyrmasyny goýuň; Men delillendirerin. {{Kod}}
Changelog / PR beýany:
Aşakdaky tapawutdan {{changelog giriş / PR düşündiriş}} ýazyň. Formaty: Näme üýtgedi (ulanyjy dilinde), Näme üçin (mesele: {{...}}), Üýtgeşmäni bozmak (bar bolsa), synagdan geçirildi. Tomaşaçylary nyşana almak üçin tehniki jargony sazlaň. {{Diff}}
Gowşak haýyş / Güýçli haýyş
Gowşak: "Bu taslama üçin README ýazyň."
Güýçli: "Maksatly diňleýjiler: bu repony ilkinji gezek klonlaşdyrýan dörediji. Birikdirilen paket.json, docker-compose.yml we skriptler / bukjanyň esasynda Maksat, talaplar, gurnama, operasiýa, synag, goşant bölümleri bilen README taslamasyny ýazyň. Bu faýllardan buýruklary çykaryň, olary VER bilen belläň.
Güýçli wersiýa diňleýjilere, çeşmä, gurluşa we “ýasamak, bellik etmek” düzgünini berýär; resminama hakyky faýllara esaslanýar we barlanmaly ýerler aýdyň görünýär.
Resminamanyň görnüşi
AI gowy edýär
Adam goşýar / tassyklaýar
README gurmak
ädim meýilnamasy
Basgançaklary işlediň we tassyklaň
Docstring / API
Gurluşy, parametri, görnüşi
Dogry görnüşi we "näme üçin"
Kod düşündiriş
"Ol näme edýär" gysgaça mazmuny
"Näme üçin bu" delil?
Çangelog / PR
birinji taslama
Täsir we takyklyk
Binagärlik karary (ADR)
skelet
Hakyky kararlar we ylalaşyklar
Resminamalar tehniki hyzmaty talap edýär
Resminamanyň iň howply tarapy, ýalan bolsa-da dogry görünse. Kod üýtgese we resminama täzelenmese, okyjyny işjeň ýalňyşýar. AI täzelenmegi aňsatlaşdyrýar: tapawut goýuň we "resminamanyň haýsy böleklerine täsir edýär?" sorap bilersiňiz. It'söne bu iň täze maglumatlary üpjün edýär - resminamalary täzelemegiň koduny üýtgetmegiň bir bölegini ediň (PR-ni kabul etmegiň ölçegi). AI çaltlaşýar; Topar tertip-düzgüni döredýär.
Üns beriň: README-de gurnama ädimlerini barlamazdan çap etmäň. "Mümkin işleýän" resminama täze döredijiniň ilkinji gününi bozup, ynamy ýitirip biler. Basgançaklary arassa gurşawda işlediň.
Adaty ýalňyşlyklar
- AI-e gabat gelmek üçin “näme üçin” almak. Sealňyş delillendirmek hiç hili aklamakdan erbetdir; Kod eýesi dizaýn sebäbini ýazmalydyr.
- Gurmak ädimlerini barlamaýan. Işlemeýän README ynamy ýok edýär.
- Kody gaýtalaýan gereksiz teswir. Hakyky "näme üçin" düşündirişleri gizläp, ses çykarýar.
- Maksatly diňleýjini görkezmezlik. Kime ýazylandygy belli bolmadyk resminamanyň ýa-da hünärmeniň peýdasy ýok.
- Täzelenmäni amaldan aýyrmak. Resminama kod bilen täzelenmese, çalt ýalňyşýar.
Gysgaça
AI mehaniki ýüküň köpüsini resminamalardan alýar: README çalt resminamalary, docstring, API salgylanmasy, changelog we PR beýany. Emma iň gymmatly gatlak bolan "näme üçin" bilip bilmeýär we ony düzmek howply. Zähmet bölünişi düşnüklidir: AI “näme / nädip” öndürýär, “näme üçin” goşýarsyňyz. Tomaşaçylary kesgitläň, çeşmeler bilen üpjün ediň, gurluşy belläň, laýyk ýerleri belläň we her gurnama ädimini özüňiz işlediň. Resminamalary kod üýtgetmegiň aýrylmaz bölegine öwüriň.
Programma meselesi
Resminamalary ýok ýa-da köne modul ýa-da kiçi taslama saýlaň. Ilki bilen “gurluşly README garalama” (ýa-da dokument) şablony bilen AI-den bir çyzgy dörediň; Çeşmäni we maksatly diňleýjini hökman beriň. Soňra AI-iň [VERIFY] ýa-da [Näme üçin GEREK] bellän her nokadyndan geçiň: aslynda gurnama ädimlerini işlediň we dizaýny “whys” -y öz bilimiňiz bilen dolduryň. Näçe ädim düzedilmelidigine we näçe “whys” goşandygyna üns beriň.
gözegçilik sanawy
- [] Resminamalarda "näme / nädip" we "näme üçin" gatlaklaryny tapawutlandyrýaryn.
- [] AI "näme üçin" düzmeýärin, özüm goşýaryn.
- [] Men haýal etmän maksatly diňleýjini we hakyky çeşme faýllaryny berýärin.
- [] AI tarapyndan bellenen [VERIFY] nokatlaryny hut özüm ýerine ýetirip barlaýaryn.
- [] Kody gaýtalaýan gereksiz teswirleri ýok edýärin.
- [] Kod üýtgetmesiniň resminamalary täzeleme bölegini edýärin.