Riba:
- Ikon samar da README, docstring da zane-zanen canji dangane da masu sauraron da aka yi niyya da tushe tare da AI
- Ikon raba 'menene/ta yaya' da 'me yasa' yadudduka a cikin takardu da ƙara 'me yasa' a matsayin ɗan adam
- Tabbatar da matakan shigarwa ta hanyar gudanar da su da kansu da sanya takardan zama wani ɓangare na canjin lambar
Mafi yawan sakaci amma mafi dadewa na ɓangaren software shine takaddun bayanai. Ana iya karanta lambar ko da bayan watanni; Wanda ya rubuta ya tafi, an manta da mahallin, kuma abin da aka rubuta kawai ya rage. Kyakkyawan README (takardar gabatarwa da ke bayyana abin da aikin yake da yadda za a girka da gudanar da shi), bayanin lambar bayanin lamba da takaddun API na yau da kullun (maganin da ke bayyana yadda ake amfani da keɓancewa) kai tsaye yana ƙayyade saurin ƙungiyar. AI yana ɗaukar yawancin "gajiya rubutu" daga cikin takardu - amma ya zo tare da tarko: AI na iya yin la'akari daga lambar abin da yake yi, amma sau da yawa ba zai iya sanin dalilin da yasa aka yi haka ba.
A cikin wannan rukunin, zaku koyi yadda ake samar da README, sharhi na lamba, docstring (blocker block rubuta kowane aiki / aji), takaddar API da canji tare da AI; da kuma yadda za a adana mafi mahimmancin ɓangaren takardun: "me yasa."
Bambance tsakanin "Me" da "Me ya sa"
Akwai nau'ikan takardu guda biyu. Na farko shine menene/yadda: "wannan aikin yana tsara lissafin", "gudanar da wannan umarni don shigarwa". Ana iya fitar da waɗannan daga lambar da tsarin; AI yayi fice a nan. Na biyu, me yasa: "me yasa muka sanya wannan sabis ɗin ya kasance asynchronous maimakon aiki tare", "me yasa wannan ƙimar iyaka ta 30 seconds", "me yasa muka zaɓi wannan ɗakin karatu akan ɗayan". Ba a rubuta waɗannan a cikin lambar ba; Samfurin yanke shawara ne na ƙira, takurawa, da ciwon baya.
AI bai san "me yasa" ba; A mafi kyau, yana yin zato mai ma'ana - wanda yake da haɗari, saboda dalili mara kyau ya fi muni fiye da wani dalili. Don haka rabon aiki a bayyane yake: AI ya tsara “menene/ta yaya,” kun ƙara “me yasa.” Sharhi mafi mahimmanci shine wanda ya faɗi abin da lambar ba zai iya faɗi ba.
Tukwici: Kada a maimaita tare da sharhi abin da lambar kanta ta faɗi a sarari (kamar i = i + 1 // ƙara i da ɗaya). AI wani lokaci yana samar da irin waɗannan maganganun da ba su da yawa; Kawar da su kuma ba da kuzarin ku don yin sharhi "me yasa".
Mataki-mataki: Ƙirƙirar Rubuce-rubuce tare da AI
- Ƙayyade masu sauraron da aka yi niyya. "Mai haɓakawa yana farawa," "Ƙungiyar waje da za ta yi amfani da wannan API," "ni gaba" - masu sauraro suna saita sautin harshe da zurfi.
- Bada tushen. Ƙara lambar da ta dace, README data kasance, misali amfani da gaggawa. Takardar da ba a samo asali ba ita ce gayyata zuwa ƙirƙira.
- Tsarin sakawa. Madaidaitan sassan don README (Manufa, Shigarwa, Amfani, Kanfigareshan, Gudunmawa), tsarin aiki don docstring.
- Yi alama a wuraren "me yasa" Tambayi AI don sanya alamar yanke shawara waɗanda ba ta san dalilin ba a matsayin "abin da ya sa" ana buƙatar bayanin kula anan"; Sa'an nan kuma ku cika waɗannan wuraren.
- Tabbatar. A zahiri gudanar da matakan shigarwa; gwada lambar samfurin. KARATUN da ba ya aiki ya fi ba README kwata-kwata.
Mini Cases guda uku
Hali na 1 - README yana haɓaka hawan jirgi. Wani buɗaɗɗen kayan aikin README ya ɓace; Sabbin masu ba da gudummawa sun yi kokawa tare da shigarwa na matsakaicin sa'o'i 2. Ƙungiyar ta ba da rubutun shigarwa da kunshin.json zuwa AI kuma sun tsara tsarin README, sannan suka gudanar da matakan da kansu a kan na'ura mai tsabta kuma sun kara da abubuwan dogara guda biyu da suka ɓace. Lokacin shigarwa don masu ba da gudummawa na gaba ya ragu zuwa matsakaicin mintuna 25.
Shari'a 2 - Tarkon da aka yi "me yasa". Wani mai haɓakawa ya tambayi AI don sharhi kusa da ƙimar ƙarewar lokaci (lokacin ƙarewa = 30). AI ta rubuta hujja mai ma'ana amma ba daidai ba "don jure rashin jinkirin hanyar sadarwa"; ainihin dalilin shine iyakar kwangilar daƙiƙa 30 na sabis na ƙasa. Fassara na kuskure ya haifar da mai haɓakawa na gaba don haɓaka ƙimar ba dole ba, wanda ya haifar da wani lamari. Darasi: dole ne mai lambar ya tabbatar da hujjar.
Case 3 - Matsayin Docstring ya zama mai sarrafa kansa. Ƙaƙwalwar ƙarami tare da ayyuka 40 ba shi da ƙididdiga. An bai wa AI tsarin aikin (style Google) kuma ya samar da siga, dawowa da bayanin keɓancewa ga kowane aiki; Mai haɓakawa ya sake nazarin waɗannan kuma ya gyara wasu ƴan shela irin na kuskure. Takaddun ayyuka 40 ya ragu daga kusan rabin yini zuwa sa'a guda.
Samfura guda huɗu masu Kwafi
Tsarin README:
Masu sauraro masu manufa: {{misali. sabon mai ba da gudummawa}}.Rubuta daftarin aiki README dangane da fayilolin da ke ƙasa. Sashe: Manufa, Siffofin, Bukatu, Shigarwa, Aiki, Kanfigareshan, Gwaji, Gudunmawa. Cire shigarwa / umarni masu gudana daga ainihin fayiloli; DAFATAN. Yi alama a wuraren da ba ku da tabbas da "[VERIFY]". Source: {{package.json / scripts / samfurin code}}
Maganar Docstring/API:
Rubuta docstring zuwa waɗannan ayyuka a cikin {{Salon aikin: Google/NumPy/JSDoc}} tsari: taƙaitaccen taƙaitawa, sigogi (nau'in + ma'ana), dawowa, keɓancewar jefawa, gajeriyar misali 1. Kar a sake maimaita abin da lambar ta ce CLEARLY. Alama yanke shawarwarin ƙira waɗanda ke buƙatar "me yasa" a matsayin "[MENENE WAJABTA]", kar a rubuta hujjar ƙirƙira.{{code}}
Cire sarari don sharhin "me yasa":
A cikin wannan lambar, mai haɓakawa na gaba zai iya tambaya "me yasa haka haka?" (lambobin sihiri, yanke shawara da ba a saba gani ba, abubuwan aiki). Ba da sharhi SKELETON ga kowannensu, amma bar dalilin BLANK; Zan cika dalilin. {{code}}
Bayanin Changelog/PR:
Rubuta {{canjin shigarwa / bayanin PR}} daga bambancin da ke ƙasa. Tsarin: Abin da ya canza (a cikin harshen mai amfani), Me yasa (fitilar: {{...}}), Karɓar canji (idan akwai), An gwada shi. Daidaita jargon fasaha don masu sauraro.{{diff}}
Rauni mai ƙarfi / Ƙarfi mai ƙarfi
Rauni: "Rubuta README don wannan aikin."
Ƙarfafa: "Masu sauraro na manufa: mai haɓakawa yana rufe wannan repo a karon farko. Dangane da kunshin da aka haɗe.json, docker-compose.yml da rubutun / babban fayil, rubuta daftarin README tare da Manufa, Bukatun, Shigarwa, Aiki, Gwaji, Taimakawa sassan. Cire umarni daga waɗannan fayiloli, kada ku tabbatar da su;
Sigar mai ƙarfi tana ba masu sauraro, tushen, tsari, da tsarin "sa shi, yi alama"; ta yadda daftarin aiki ya dogara da ainihin fayiloli kuma wuraren da za a tantance su a bayyane suke.
Nau'in takarda
AI yayi kyau
Mutum yana ƙarawa / tabbatarwa
Shigar README
shaci mataki
Gudun matakan kuma tabbatar
Docstring/API
Tsarin, siga, nau'in
Nau'in daidai kuma "me yasa"
Sharhi na lamba
"Abin da yake yi" summary
"Me yasa wannan" barata
Canje-canje / PR
daftarin farko
Tasiri da daidaito
Shawarar Architectural (ADR)
kwarangwal
Hukunce-hukuncen gaske da sasantawa
Takardun Yana Bukatar Kulawa
Mafi hatsarin al'amari na takarda shine lokacin da ta bayyana gaskiya ko da yake karya ce. Lokacin da lambar ta canza kuma ba a sabunta takaddun ba, tana ɓatar da mai karatu sosai. AI yana sauƙaƙa ɗaukakawa: fitar da bambanci kuma ku tambayi "wane sassa na takaddar wannan canjin ya shafi?" kuna iya tambaya. Amma tsari ne wanda ke tabbatar da sabuntawar zamani - sanya sabuntawar takaddun wani ɓangare na canjin lambar (ma'aunin karɓa na PR). AI yana haɓaka; Ƙungiyar tana gina horo.
Tsanaki: Kar a buga ba tare da tabbatar da matakan shigarwa a cikin README ba. Takaddun "wataƙila aiki" na iya lalata sabuwar ranar farko ta mai haɓakawa kuma ta zubar da amana. Gudun matakan da kanku a cikin yanayi mai tsabta.
Kuskuren gama gari
- Samun "me yasa" don dacewa da AI. Bada hujjar karya ta fi rashin hujja; Mai lambar ya kamata ya rubuta dalilin ƙira.
- Rashin tabbatar da matakan shigarwa. KARANTA wanda baya aiki yana lalata amana.
- Bayanin da ba dole ba yana maimaita lambar. Yana haifar da hayaniya, yana ɓoye ainihin fassarori "me yasa".
- Ba a fayyace masu sauraro da aka yi niyya ba. Takardar da ba a san wanda aka rubuta wa ba ba ta da wani amfani ga novice ko gwani.
- Rabe sabuntawa daga tsari. Idan ba a sabunta daftarin aiki tare da lambar ba zai zama mai ruɗi da sauri.
A takaice
AI yana ɗaukar yawancin nauyin injina daga takaddun bayanai: saurin zane README, docstring, API reference, changelog da PR kwatancen. Amma ba zai iya sanin dalilin da ya sa ba, wanda shine mafi mahimmancin Layer, kuma yana da haɗari don yin shi. Rarraba aikin a bayyane yake: AI yana samar da "menene/ta yaya," kun ƙara "me yasa." Ƙayyade masu sauraro, samar da albarkatu, sanya tsari, alamar wuraren da za su dace, da kuma tabbatar da kowane mataki na shigarwa ta hanyar tafiyar da shi da kanka. Sanya takardun zama wani sashe mai mahimmanci na canjin lambar.
Aikin aikace-aikace
Zaɓi samfuri ko ƙaramin aiki wanda takaddun bayanansa ya ɓace ko tsufa. Da farko samar da jita-jita daga AI tare da samfurin "tsarin README" (ko docstring); Tabbatar ba da tushe da masu sauraro masu niyya. Sa'an nan kuma ku shiga kowane wuri inda AI ta yi alama [TABBATA] ko [ME YA SA AKE BUKATA]: a zahiri gudanar da matakan saitin kuma cika ƙirar "me yasa" tare da ilimin ku. Kula da matakai nawa ne ake buƙatar gyarawa da nawa "me yasa" kuka ƙara.
jerin abubuwan dubawa
- [ ] A cikin takardun, na bambanta yadudduka "mene/yadda" da "me yasa".
- [ ] Ba na sanya AI ta zama "me yasa", na ƙara da kaina.
- [ ] Ina ba da hanzarin masu sauraron da aka yi niyya da ainihin fayilolin tushen.
- [ ] Na tabbatar da maki [VERIFY] da AI ta yi wa alama ta hanyar aiwatar da su da kaina.
- [ ] Ina kawar da maganganun da ba dole ba waɗanda ke maimaita lambar.
- [ ] Ina yin sabuntawar takaddun ɓangaren canjin lambar.