Hati, README na Maoni ya Kanuni

Faida:

• Uwezo wa kutengeneza README, docstring na rasimu za mabadiliko kulingana na hadhira lengwa na chanzo na AI
• Uwezo wa kutenganisha tabaka za 'nini/vipi' na 'kwanini' kwenye nyaraka na kuongeza 'kwanini' kama binadamu.
• Kuthibitisha hatua za usakinishaji kwa kuziendesha kibinafsi na kufanya hati kuwa sehemu ya mabadiliko ya msimbo

Sehemu inayopuuzwa mara kwa mara lakini inayodumu kwa muda mrefu zaidi ya programu ni hati. Kanuni hiyo inasomeka hata baada ya miezi; Aliyeandika amekwenda, muktadha umesahaulika, na ni kile kilichoandikwa tu. README nzuri (hati ya utangulizi inayofafanua mradi ni nini na jinsi ya kuusakinisha na kuuendesha), maoni ya msimbo wa maelezo na hati ya API iliyosasishwa (rejeleo linalofafanua jinsi ya kutumia kiolesura) huamua moja kwa moja kasi ya timu. AI inachukua "uchovu mwingi wa kuandika" nje ya hati - lakini inakuja na mtego: AI inaweza kukisia kutoka kwa msimbo kile inachofanya, lakini mara nyingi haiwezi kujua kwa nini inafanywa kwa njia hiyo.

Katika kitengo hiki, utajifunza jinsi ya kutoa README, maoni ya msimbo, docstring (kizuizi cha maoni kimeandikwa kwa kila kitendakazi/darasa), hati ya API na logi ya mabadiliko na AI; na jinsi ya kuhifadhi kibinadamu sehemu muhimu zaidi ya hati: "kwa nini."

Tofauti kati ya "Nini" na "Kwanini"

Kuna tabaka mbili za nyaraka. Ya kwanza ni nini/jinsi gani: "kitendaji hiki hupanga orodha", "endesha amri hii ili kusakinisha". Hizi zinaweza kutolewa kutoka kwa kanuni na muundo; AI inafaulu hapa. Pili, kwa nini: "kwa nini tulifanya huduma hii kuwa ya asynchronous badala ya kusawazisha", "kwa nini kikomo hiki kina thamani ya sekunde 30", "kwa nini tulichagua maktaba hii juu ya nyingine". Haya hayakuandikwa kwenye kanuni; Ni zao la maamuzi ya kubuni, vikwazo, na maumivu ya zamani.

AI haijui "kwa nini"; Bora zaidi, hutengeneza kisio la kuridhisha—ambalo ni hatari, kwa sababu sababu isiyo sahihi ni mbaya zaidi kuliko kutokuwa na sababu hata kidogo. Kwa hivyo mgawanyiko wa kazi uko wazi: AI inatayarisha "nini/vipi," unaongeza "kwa nini." Maoni ya thamani zaidi ni yale yanayosema kile ambacho kanuni haiwezi kusema.

Kidokezo: Usirudie kwa maoni kile kanuni yenyewe inasema wazi (kama i = i + 1 // ongeza i kwa moja). AI wakati mwingine hutoa maoni yasiyofaa kama haya; Waondoe na utoe nguvu zako kwa maoni ya "kwa nini".

Hatua kwa Hatua: Uzalishaji wa Hati na AI

1. Bainisha hadhira lengwa. "Msanidi programu anayeanza," "timu ya nje ambayo itatumia API hii," "mimi ya baadaye" - hadhira huweka sauti ya lugha na kina.
2. Toa chanzo. Ongeza msimbo husika, README iliyopo, matumizi ya mfano kwenye kidokezo. Hati isiyo na chanzo ni mwaliko wa kutengeneza.
3. Muundo wa kulazimisha. Sehemu za kawaida za README (Madhumuni, Usakinishaji, Matumizi, Usanidi, Mchango), umbizo la mradi la mfuatano wa hati.
4. Weka alama kwenye nafasi za "kwanini". Uliza AI kuashiria maamuzi ambayo haijui mantiki kama "noti ya 'kwa nini' inahitajika hapa"; Kisha unajaza nafasi hizo.
5. Thibitisha. Kweli kukimbia hatua za ufungaji; jaribu nambari ya sampuli. SOMA ambayo haifanyi kazi ni mbaya zaidi kuliko kukosa KUSOMA kabisa.

Kesi Tatu Ndogo

Kesi ya 1 - README imeharakishwa kuabiri. README ya chombo huria haikuwepo; Wachangiaji wapya walitatizika kusakinisha kwa wastani wa saa 2. Timu ilitoa hati za usakinishaji na package.json kwa AI na kuandaa README iliyoundwa, kisha ikaendesha hatua zenyewe kwenye mashine safi na kuongeza tegemezi mbili zinazokosekana. Muda wa kusakinisha kwa wachangiaji waliofuata ulipungua hadi wastani wa dakika 25.

Kesi ya 2 - Mtego wa "kwanini" iliyoundwa. Msanidi programu aliuliza AI kwa maoni karibu na thamani ya kuisha (timeout=30). AI iliandika sababu nzuri lakini isiyo sahihi "kuvumilia latency ya juu ya mtandao"; sababu halisi ilikuwa kikomo cha kandarasi cha sekunde 30 cha huduma ya chini. Ufafanuzi huo usio sahihi ulisababisha msanidi programu aliyefuata kuongeza thamani isivyo lazima, na kusababisha tukio. Somo: mwenye msimbo lazima athibitishe uhalalishaji.

Kesi ya 3 - Kiwango cha Docstring kimejiendesha kiotomatiki. Moduli kisaidizi iliyo na vitendaji 40 haikuwa na masharti ya hati. AI ilipewa muundo wa mradi (mtindo wa Google) na ikatoa parameta, maelezo ya kurudi na ubaguzi kwa kila kazi; Msanidi alikagua haya na kurekebisha matamko machache ya aina isiyo sahihi. Kuhifadhi kumbukumbu za utendaji 40 kulishuka kutoka takriban nusu siku hadi saa moja.

Violezo Vinne Vinakiliwa

Rasimu ya README Iliyoundwa:

Hadhira inayolengwa: {{k.m. mchangiaji mpya}}. Andika rasimu ya README kulingana na faili zilizo hapa chini. Sehemu: Madhumuni, Vipengele, Mahitaji, Ufungaji, Uendeshaji, Usanidi, Upimaji, Mchango. Dondoo za usakinishaji/kuendesha amri kutoka kwa faili halisi; KUFAA. Weka alama kwenye maeneo ambayo huna uhakika na "[THIBITISHA]". Chanzo: {{package.json / scripts / sampuli code}}

Rejeleo la Docstring/API:

Andika muundo wa hati kwa chaguo hizi za kukokotoa katika umbizo la {{project style: Google/NumPy/JSDoc}}: muhtasari mfupi, vigezo (aina + maana), kurudi, vighairi vilivyotupwa, mfano 1 mfupi. Usirudie kile kanuni inasema KWA UWAZI. Tia alama kwenye maamuzi ya muundo yanayohitaji "kwa nini" kuwa "[WHY LAZIMA]", usiandike sababu za kubuniwa.{{code}}

Ondoa nafasi za maoni ya "kwanini":

Katika nambari hii, msanidi programu anayefuata anaweza kuuliza "kwa nini hii ni hivyo?" (nambari za uchawi, maamuzi yasiyo ya kawaida, workarounds). Toa maoni SKELETON kwa kila moja, lakini acha mantiki TUPU; Nitajaza uhalalishaji.{{code}}

Taarifa ya Changelog/PR:

Andika {{changelog entry / PR description}} kutoka kwa tofauti iliyo hapa chini. Umbizo: Nini kilibadilika (katika lugha ya mtumiaji), Kwa nini (toleo: {{...}}), Mabadiliko yanayovunja (kama yapo), Je, yamejaribiwa. Rekebisha jargon ya kiufundi kwa hadhira lengwa.{{diff}}

Agizo dhaifu / Ukumbusho thabiti

Dhaifu: "Andika README kwa mradi huu."

Imara: "Hadhira inayolengwa: msanidi anayeunda repo hii kwa mara ya kwanza. Kulingana na kifurushi kilichoambatishwa.json, docker-compose.yml na scripts/folda, andika rasimu ya README yenye Madhumuni, Mahitaji, Usakinishaji, Uendeshaji, Majaribio, Mchango. Toa amri kutoka kwa faili hizi, usizifanye; weka alama [VERYIF] popote ambapo huna uhakika."

Toleo lenye nguvu huwapa hadhira, chanzo, muundo, na kanuni ya "ifanye, iweke alama"; ili hati itegemee faili halisi na maeneo ya kuthibitishwa yaonekane wazi.

Aina ya hati

AI inafanya vizuri

Binadamu anaongeza/anathibitisha

Usakinishaji wa README

muhtasari wa hatua

Endesha hatua na uthibitishe

Docstring/API

Muundo, parameter, aina

Aina sahihi na "kwa nini"

Maoni ya kanuni

"Anachofanya" muhtasari

"Kwa nini hii" kuhesabiwa haki

Changelog/PR

rasimu ya kwanza

Athari na usahihi

Uamuzi wa Usanifu (ADR)

mifupa

Maamuzi ya kweli na maelewano

Nyaraka Zinahitaji Matengenezo

Kipengele hatari zaidi cha hati ni wakati inaonekana kuwa kweli ingawa ni ya uwongo. Wakati msimbo unabadilika na hati haijasasishwa, inapotosha msomaji kikamilifu. AI hurahisisha kusasisha: toa tofauti na uulize "mabadiliko haya yanaathiri sehemu gani za hati?" unaweza kuuliza. Lakini ni mchakato unaohakikisha kusasishwa - fanya usasishaji wa hati kuwa sehemu ya mabadiliko ya msimbo (kigezo cha kukubalika cha PR). AI huongeza kasi; Timu hujenga nidhamu.

Tahadhari: Usichapishe bila kuthibitisha hatua za usakinishaji katika README. Hati ya "pengine ya kazi" inaweza kuharibu siku ya kwanza ya msanidi programu na kuondoa uaminifu. Endesha hatua mwenyewe katika mazingira safi.

Makosa ya kawaida

• Kupata "kwa nini" kutoshea AI. Kuhesabiwa haki kwa uwongo ni mbaya zaidi kuliko kutokuwa na haki; Mmiliki wa msimbo anapaswa kuandika sababu ya muundo.
• Haidhibitishi hatua za usakinishaji. README ambayo haifanyi kazi inaharibu uaminifu.
• Maoni yasiyo ya lazima yanayorudia msimbo. Inazalisha kelele, inayoficha tafsiri halisi za "kwanini".
• Bila kubainisha hadhira lengwa. Hati ambayo haijulikani imeandikwa kwa nani haina manufaa kwa novice au mtaalamu.
• Kutenganisha sasisho kutoka kwa mchakato. Ikiwa hati haijasasishwa na msimbo, inapotosha haraka.

Kwa muhtasari

AI inachukua mzigo mwingi wa kiufundi nje ya hati: rasimu za haraka README, docstring, rejeleo la API, mabadiliko ya kumbukumbu na maelezo ya PR. Lakini haiwezi kujua "kwa nini", ambayo ni safu ya thamani zaidi, na ni hatari kuifanya. Mgawanyo wa kazi uko wazi: AI hutoa "nini/vipi," unaongeza "kwa nini." Bainisha hadhira, toa nyenzo, weka muundo, weka alama mahali panapofaa, na uthibitishe kila hatua ya usakinishaji kwa kuiendesha wewe mwenyewe. Fanya hati ziwe sehemu muhimu ya mabadiliko ya msimbo.

Jukumu la maombi

Chagua moduli au mradi mdogo ambao hati zake hazipo au zimepitwa na wakati. Kwanza toa muhtasari kutoka kwa AI na kiolezo cha "rasimu ya README" (au kamba ya hati); Hakikisha kutoa chanzo na hadhira lengwa. Kisha pitia kila sehemu ambapo AI imeweka alama [THIBITISHA] au [KWANINI Inahitajika]: kwa kweli endesha hatua za usanidi na ujaze muundo wa "kwanini" kwa maarifa yako mwenyewe. Kumbuka ni hatua ngapi zinahitaji kurekebishwa na ni "kwa nini" ngapi umeongeza.

orodha ya ukaguzi

• [ ] Katika hati, ninatofautisha tabaka za "nini/vipi" na "kwanini".
• [ ] Sifanyi AI kuunda "kwanini", naiongeza mwenyewe.
• [ ] Ninatoa dodoso kwa hadhira lengwa na faili halisi za chanzo.
• [ ] Ninathibitisha alama za [HAKIKISHA] zilizowekwa alama na AI kwa kuzitekeleza kibinafsi.
• [ ] Ninaondoa maoni yasiyo ya lazima ambayo yanarudia msimbo.
• [ ] Ninafanya sasisho la hati kuwa sehemu ya mabadiliko ya msimbo.