Daromadlar:
- AI bilan maqsadli auditoriya va manba asosida README, docstring va changelog loyihalarini ishlab chiqish qobiliyati
- Hujjatlarda "nima/qanday" va "nima uchun" qatlamlarini ajratish va inson sifatida "nima uchun" qo'shish qobiliyati
- O'rnatish bosqichlarini shaxsan ishga tushirish va hujjatni kodni o'zgartirishning bir qismi qilish orqali tekshirish
Dasturiy ta'minotning eng ko'p e'tibordan chetda qoladigan, lekin eng uzoq davom etadigan qismi bu hujjatlardir. Kod bir necha oydan keyin ham o'qilishi mumkin; Uni yozgan odam ketdi, kontekst unutiladi, faqat yozilgani qoladi. Yaxshi README (loyiha nima ekanligini va uni qanday o'rnatish va ishga tushirishni tushuntiruvchi kirish hujjati), tushuntirish kodlari sharhlari va so'nggi API hujjatlari (interfeysdan qanday foydalanishni tushuntiruvchi ma'lumotnoma) bevosita jamoa tezligini aniqlaydi. AI ko‘p “yozish charchoqlarini” hujjatlardan olib tashlaydi — lekin bu tuzoq bilan birga keladi: AI koddan nima qilayotganini xulosa qilishi mumkin, lekin ko‘pincha nima uchun bunday qilinganini bila olmaydi.
Ushbu bo'limda siz AI bilan README, kod sharhi, docstring (funktsiya/sinf uchun yozilgan sharh bloki), API hujjati va o'zgarishlar jurnalini qanday yaratishni o'rganasiz; va hujjatlarning eng qimmatli qismini inson tomonidan qanday saqlash kerak: "nima uchun".
"Nima" va "Nima uchun" o'rtasidagi farq
Hujjatlarning ikki qatlami mavjud. Birinchisi, nima/qanday: "bu funksiya ro'yxatni tartiblaydi", "o'rnatish uchun ushbu buyruqni ishga tushiring". Ular kod va tuzilmadan olinishi mumkin; AI bu erda ustundir. Ikkinchidan, nima uchun: "nima uchun biz bu xizmatni sinxron emas, balki asinxron qildik", "nima uchun bu chegara qiymati 30 soniya", "nima uchun biz bu kutubxonani boshqasidan ko'ra tanladik". Bular kodda yozilmagan; Bu dizayn qarorlari, cheklovlar va o'tmishdagi og'riqlar mahsulidir.
AI "nima uchun" ni bilmaydi; Eng yaxshi holatda, bu o'rtacha taxminni keltirib chiqaradi - bu xavfli, chunki noto'g'ri sabab hech qanday sabab yo'qligidan ham yomonroqdir. Shunday qilib, mehnat taqsimoti aniq: AI "nima/qanday" loyihasini ishlab chiqadi, siz "nima uchun" ni qo'shasiz. Eng qimmatli sharh - bu kod aytolmaydigan narsani aytadi.
Maslahat: Kodning o'zi aniq aytilgan narsani sharh bilan takrorlamang (masalan, i = i + 1 // i ni bittaga oshiring). AI ba'zida bunday ortiqcha izohlarni ishlab chiqaradi; Ularni yo'q qiling va kuchingizni "nima uchun" sharhlariga bag'ishlang.
Bosqichma-bosqich: AI yordamida hujjat yaratish
- Maqsadli auditoriyani belgilang. "Endi boshlayotgan dasturchi", "ushbu APIdan foydalanadigan tashqi jamoa", "kelajakdagi men" - tomoshabinlar til va chuqurlik uchun ohangni o'rnatadilar.
- Manbani bering. So'rovga tegishli kodni, mavjud README, foydalanish misolini qo'shing. Manbasiz hujjat - bu uydirmaga taklif.
- Impozitsiya tuzilishi. README uchun standart bo'limlar (maqsad, o'rnatish, foydalanish, konfiguratsiya, hissa), docstring uchun loyiha formati.
- "Nima uchun" bo'shliqlarini belgilang. AIdan mantiqiy asosini bilmagan qarorlarni "bu erda "nima uchun" yozuvi kerak" deb belgilashni so'rang; Keyin bu bo'shliqlarni to'ldirasiz.
- Tasdiqlash. Aslida o'rnatish bosqichlarini bajaring; namuna kodini sinab ko'ring. Ishlamaydigan README umuman README yo'qligidan yomonroq.
Uchta mini korpus
1-holat - README tezlashtirilgan ishga tushirish. Ochiq manbali vositaning README fayli yo‘q edi; Yangi ishtirokchilar o'rnatish bilan o'rtacha 2 soat kurashdilar. Jamoa o‘rnatish skriptlari va package.json ni sun’iy intellektga berdi va tuzilgan README loyihasini tuzdi, so‘ngra qadamlarni o‘zlari toza mashinada bajardi va ikkita etishmayotgan bog‘liqlikni qo‘shdi. Keyingi ishtirokchilar uchun o'rnatish vaqti o'rtacha 25 daqiqagacha qisqardi.
2-holat - "Nima uchun" tuzog'i. Ishlab chiquvchi AIdan vaqt tugashi qiymati yonida izoh berishni so'radi (timeout = 30). AI "tarmoqning yuqori kechikishiga toqat qilish uchun" oqilona, ammo noto'g'ri asoslashni yozgan; haqiqiy sabab quyi oqim xizmatining shartnoma bo'yicha 30 soniyalik chegarasi edi. Noto'g'ri talqin qilish keyingi ishlab chiquvchini qiymatni keraksiz ravishda oshirishga olib keldi va bu hodisaga olib keldi. Dars: kod egasi asoslashni tekshirishi kerak.
3-holat - Docstring standarti avtomatlashtirilgan. 40 ta funksiyaga ega yordamchi modulda hujjatlar qatorlari yoʻq edi. AIga loyiha formati (Google uslubi) berildi va har bir funktsiya uchun parametr, qaytish va istisno tavsiflarini ishlab chiqdi; Ishlab chiquvchi ularni ko'rib chiqdi va bir nechta noto'g'ri turdagi deklaratsiyalarni tuzatdi. 40 ta funksiyani hujjatlashtirish taxminan yarim kundan bir soatgacha qisqardi.
To'rt nusxa ko'chirish shablonlari
Strukturaviy README loyihasi:
Maqsadli auditoriya: {{masalan, new contributor}}.Quyidagi fayllar asosida README loyihasini yozing. Bo'limlar: Maqsad, Xususiyatlar, Talablar, O'rnatish, Ishlash, Konfiguratsiya, Sinov, Hissa. Haqiqiy fayllardan o'rnatish/ishlash buyruqlarini chiqarib oling; FITTING. Ishonchingiz komil boʻlmagan joylarni “[TASHQIRISH]” bilan belgilang. Manba: {{package.json / skriptlar / namuna kodi}}
Docstring/API havolasi:
Ushbu funksiyalarga docstringni {{project style: Google/NumPy/JSDoc}} formatida yozing: qisqa xulosa, parametrlar (tur + ma'no), qaytish, tashlangan istisnolar, 1 ta qisqa misol. Kodda aniq aytilgan narsalarni takrorlamang. “Nima uchun” talab qilinadigan dizayn qarorlarini “[NEGA KERAK]” deb belgilang, uydirma asoslashni yozmang.{{code}}
"Nima uchun" sharhi uchun bo'sh joylarni olib tashlang:
Ushbu kodda keyingi ishlab chiquvchi "nega bunday?" Deb so'rashi mumkin. (sehrli raqamlar, g'ayrioddiy qarorlar, vaqtinchalik echimlar). Har biri uchun SKELETON sharhini bering, lekin mantiqiy asosni BLANK qoldiring; Men asoslashni to'ldiraman.{{code}}
Changelog/PR bayonoti:
Quyidagi farqdan {{changelog entry / PR description}} yozing. Format: Nima o'zgargan (foydalanuvchi tilida), Nima uchun (muammo: {{...}}), O'zgarish (agar mavjud bo'lsa), U sinovdan o'tganmi. Texnik jargonni maqsadli auditoriyaga moslang.{{diff}}
Zaif taklif / Kuchli taklif
Zaif: "Ushbu loyiha uchun README yozing."
Kuchli: "Maqsadli auditoriya: ushbu reponi birinchi marta klonlayotgan dasturchi. Ilova qilingan package.json, docker-compose.yml va skriptlar/papkaga asoslanib, Maqsad, Talablar, O'rnatish, Operatsion, Sinov, Hissa bo'limlari bilan README loyihasini yozing. Bu fayllardan buyruqlarni chiqarib oling, ularni hech qanday joyda [Yo'qligini] belgilamang."
Kuchli versiya tomoshabinlar, manba, tuzilma va "yasa, belgilang" qoidasini beradi; Shunday qilib, hujjat haqiqiy fayllarga asoslangan va tekshirilishi kerak bo'lgan joylar aniq ko'rinadi.
Hujjat turi
AI yaxshi ishlaydi
Inson qo'shadi/tasdiqlaydi
README o'rnatish
qadam konturi
Qadamlarni bajaring va tasdiqlang
Docstring/API
Tuzilishi, parametri, turi
To'g'ri turi va "nima uchun"
Kod sharhi
"U nima qilyapti" xulosasi
"Nima uchun bu" asosli
Changelog/PR
birinchi qoralama
Ta'sir va aniqlik
Arxitektura qarori (ADR)
skelet
Haqiqiy qarorlar va murosalar
Hujjatlar texnik xizmat ko'rsatishni talab qiladi
Hujjatning eng xavfli tomoni, u noto'g'ri bo'lsa ham, haqiqat bo'lib ko'rinishidir. Kod o'zgarganda va hujjat yangilanmasa, u o'quvchini faol ravishda chalg'itadi. AI yangilashni osonlashtiradi: farqni chiqaring va “bu oʻzgarish hujjatning qaysi qismlariga taʼsir qiladi?” deb soʻrang. so'rashingiz mumkin. Ammo bu yangilanishni ta'minlaydigan jarayon - hujjatlarni yangilashni kodni o'zgartirishning bir qismiga aylantiring (PRni qabul qilish mezoni). AI tezlashadi; Jamoa intizomni o'rnatadi.
Diqqat: README da oʻrnatish bosqichlarini tekshirmasdan nashr qilmang. "Ehtimol, ish" hujjati yangi ishlab chiquvchining birinchi kunini buzishi va ishonchini yo'qotishi mumkin. Bosqichlarni toza muhitda o'zingiz bajaring.
Umumiy xatolar
- AIga mos keladigan "nima uchun" ni olish. Noto'g'ri oqlash oqlanishdan ko'ra yomonroqdir; Kod egasi dizayn sababini yozishi kerak.
- O'rnatish bosqichlarini tasdiqlamaslik. Ishlamaydigan README ishonchni yo'q qiladi.
- Kodni takrorlaydigan keraksiz izoh. Haqiqiy "nima uchun" talqinlarini yashirib, shovqin chiqaradi.
- Maqsadli auditoriyani aniqlamaslik. Kimga yozilgani noma'lum hujjat yangi boshlovchiga ham, mutaxassisga ham foyda bermaydi.
- Yangilanishni jarayondan ajratish. Agar hujjat kod bilan yangilanmasa, u tezda noto'g'ri bo'ladi.
Xulosa
AI hujjatlardan mexanik yukning katta qismini oladi: tezkor qoralamalar README, docstring, API ma'lumotnomasi, o'zgarishlar jurnali va PR tavsiflari. Ammo u eng qimmatli qatlam bo'lgan "nima uchun" ni bila olmaydi va uni to'ldirish xavflidir. Mehnat taqsimoti aniq: AI "nima/qanday" ni ishlab chiqaradi, siz "nima uchun" ni qo'shasiz. Auditoriyani belgilang, resurslarni taqdim eting, tuzilmani o'rnating, mos keladigan joylarni belgilang va o'zingiz ishga tushirish orqali har bir o'rnatish bosqichini tekshiring. Hujjatlarni kodni o'zgartirishning ajralmas qismiga aylantiring.
Ilova vazifasi
Hujjatlari etishmayotgan yoki eskirgan modul yoki kichik loyihani tanlang. Avval “tuzilgan README loyihasi” (yoki docstring) shabloni bilan AIdan konturni yarating; Manba va maqsadli auditoriyani berganingizga ishonch hosil qiling. Keyin AI [TASHQIRISH] yoki [NEGA KERAK] deb belgilagan har bir nuqtadan o'ting: aslida sozlash bosqichlarini bajaring va o'zingizning bilimingiz bilan "nima uchun" dizaynini to'ldiring. Qancha qadamlarni tuzatish kerakligini va qancha "nima uchun" qo'shganingizga e'tibor bering.
nazorat ro'yxati
- [ ] Hujjatlarda men "nima/qanday" va "nima uchun" qatlamlarini ajrataman.
- [ ] Men sun'iy intellektni "nima uchun" ni tashkil qilmayman, men uni o'zim qo'shaman.
- [ ] Men taklifni maqsadli auditoriya va haqiqiy manba fayllarini beraman.
- [ ] AI tomonidan belgilangan [TASHQIRISH] nuqtalarini shaxsan bajarish orqali tasdiqlayman.
- [ ] Men kodni takrorlaydigan keraksiz izohlarni yo'q qilaman.
- [ ] Hujjatlarni yangilash kodini o'zgartirishning bir qismini qilyapman.