Qazanclar:
- AI ilə hədəf auditoriya və mənbə əsasında README, docstring və changelog layihələri hazırlamaq bacarığı
- Sənədlərdə "nə/necə" və "niyə" təbəqələrini ayırmaq və insan kimi "niyə" əlavə etmək bacarığı
- Quraşdırma addımlarını şəxsən işlətməklə və sənədi kod dəyişikliyinin bir hissəsi etməklə yoxlamaq
Proqram təminatının ən çox diqqətdən kənarda qalan, lakin ən uzunömürlü hissəsi sənədlərdir. Kod aylar sonra da oxuna bilər; Onu yazan getdi, kontekst unudulub, yalnız yazılanlar qalır. Yaxşı README (layihənin nə olduğunu və onun necə qurulub işə salınacağını izah edən giriş sənədi), izahlı kod şərhləri və müasir API sənədləri (interfeysdən necə istifadə olunacağını izah edən arayış) komandanın sürətini birbaşa müəyyən edir. Süni intellekt “yazma yorğunluğunun” çoxunu sənədlərdən çıxarır – lakin bu, bir tələ ilə gəlir: AI koddan nə etdiyini çıxara bilər, lakin çox vaxt bunun niyə belə edildiyini bilmir.
Bu bölmədə siz README, kod şərhi, docstring (funksiya/sinif üçün yazılmış şərh bloku), API sənədi və AI ilə dəyişiklik jurnalının necə hazırlanacağını öyrənəcəksiniz; və sənədlərin ən qiymətli hissəsini insanca necə qoruyub saxlamaq olar: “niyə”.
"Nə" və "Niyə" arasındakı fərq
Sənədlərin iki qatı var. Birincisi, nə/necə: "bu funksiya siyahı sıralayır", "quraşdırmaq üçün bu əmri işlədir". Bunlar koddan və strukturdan çıxarıla bilər; AI burada üstündür. İkincisi, niyə: "niyə biz bu xidməti sinxron deyil, asinxron etdik", "niyə bu limit dəyəri 30 saniyədir", "niyə biz bu kitabxananı digərindən seçdik". Bunlar kodda yazılmayıb; Bu, dizayn qərarlarının, məhdudiyyətlərin və keçmiş ağrıların məhsuludur.
Süni intellekt "niyə"ni bilmir; Ən yaxşı halda, bu, ağlabatan bir təxmin yaradır - bu təhlükəlidir, çünki səhv səbəb heç bir səbəb olmadan daha pisdir. Beləliklə, əmək bölgüsü aydındır: AI “nə/necə” layihəsini hazırlayır, siz “niyə” əlavə edirsiniz. Ən dəyərli şərh kodun deyə bilmədiyini söyləyən şərhdir.
İpucu: Kodun özünün aydın dediklərini şərhlə təkrarlamayın (məsələn, i = i + 1 // i-i bir artırın). AI bəzən belə lazımsız şərhlər istehsal edir; Onları aradan qaldırın və enerjinizi “niyə” şərhlərinə sərf edin.
Addım-addım: AI ilə sənədləşmənin yaradılması
- Hədəf auditoriyasını müəyyənləşdirin. “Yeni başlayan bir tərtibatçı”, “bu API-dən istifadə edəcək xarici komanda”, “gələcək mən” – tamaşaçılar dil və dərinlik tonunu təyin edir.
- Mənbəni verin. Müvafiq kodu, mövcud README-i, istifadə nümunəsini sorğuya əlavə edin. Mənbəsiz sənəd uydurma dəvətdir.
- Tətbiq strukturu. README üçün standart bölmələr (Məqsəd, Quraşdırma, İstifadə, Konfiqurasiya, Töhfə), docstring üçün layihə formatı.
- "Niyə" boşluqlarını qeyd edin. Süni intellektdən əsasını bilmədiyi qərarları “burada “niyə” qeydi tələb olunur” kimi qeyd etməyi xahiş edin; Sonra həmin boşluqları doldurursunuz.
- Doğrulayın. Əslində quraşdırma addımlarını yerinə yetirin; nümunə kodunu sınayın. İşləməyən README ümumiyyətlə README olmamasından daha pisdir.
Üç mini qutu
Case 1 — README sürətləndirilmiş işə salınma. Açıq mənbə alətinin README-i yox idi; Yeni ianəçilər quraşdırma ilə orta hesabla 2 saat mübarizə apardılar. Komanda quraşdırma skriptlərini və package.json-u AI-yə verdi və strukturlaşdırılmış README tərtib etdi, sonra addımları özləri təmiz maşında icra etdi və iki çatışmayan asılılığı əlavə etdi. Sonrakı ianəçilər üçün quraşdırma müddəti orta hesabla 25 dəqiqəyə qədər azaldı.
Case 2 - Uydurulmuş "niyə" tələsi. Tərtibatçı süni intellektdən fasilə dəyərinin yanında şərh istədi (taymout=30). Süni intellekt "yüksək şəbəkə gecikməsinə dözmək üçün" ağlabatan, lakin yanlış əsaslandırma yazdı; əsl səbəb aşağı axın xidmətinin müqavilə üzrə 30 saniyəlik limiti idi. Səhv təfsir, sonrakı tərtibatçının dəyəri lazımsız yerə artırmasına səbəb oldu və bu, insidentlə nəticələndi. Dərs: kod sahibi əsaslandırmanı yoxlamalıdır.
Case 3 — Docstring standartı avtomatlaşdırılmışdır. 40 funksiyalı köməkçi modulun sənəd sətirləri yox idi. AI-ya layihə formatı (Google stili) verildi və hər bir funksiya üçün parametr, qaytarma və istisna təsvirləri istehsal edildi; Tərtibatçı bunları nəzərdən keçirdi və bir neçə yanlış tip bəyannaməsini düzəltdi. 40 funksiyanın sənədləşdirilməsi təxminən yarım gündən bir saata qədər azaldı.
Dörd Kopyalana bilən Şablon
Strukturlaşdırılmış README layihəsi:
Hədəf auditoriyası: {{məs. yeni töhfəçi}}.Aşağıdakı fayllar əsasında README layihəsini yazın. Bölmələr: Məqsəd, Xüsusiyyətlər, Tələblər, Quraşdırma, Əməliyyat, Konfiqurasiya, Test, Töhfə. Faktiki fayllardan quraşdırma/işləyən əmrləri çıxarın; MÜRACİƏT. Əmin olmadığınız yerləri "[DOĞRULA]" ilə qeyd edin. Mənbə: {{package.json / skriptlər / nümunə kod}}
Docstring/API arayışı:
Bu funksiyalara {{layihə stili: Google/NumPy/JSDoc}} formatında sənəd yazın: qısa xülasə, parametrlər (tip + məna), qayıdış, atılan istisnalar, 1 qısa nümunə. Kodun açıq-aydın dediklərini təkrarlamayın. "Niyə" tələb edən dizayn qərarlarını "[NİYƏ LAZIMDIR]" kimi qeyd edin, uydurma əsaslandırma yazmayın.{{code}}
"Niyə" şərhi üçün boşluqları silin:
Bu kodda növbəti tərtibatçı “niyə belədir?” deyə soruşa bilər. (sehrli nömrələr, qeyri-adi qərarlar, həll yolları). Hər biri üçün SKELETON şərhini verin, lakin əsaslandırmanı BLANK qoyun; Mən əsaslandırmanı dolduracağam.{{code}}
Changelog/PR bəyanatı:
Aşağıdakı fərqdən {{dəyişiklik qeydi / PR təsviri}} yazın. Format: Nə dəyişdi (istifadəçi dilində), Niyə (məsələ: {{...}}), Qırılma dəyişikliyi (əgər varsa), Yoxlanılıbmı. Texniki jarqonu hədəf auditoriyaya uyğunlaşdırın.{{diff}}
Zəif məlumat / Güclü göstəriş
Zəif: "Bu layihə üçün README yazın."
Güclü: "Hədəf auditoriya: bu reponu ilk dəfə klonlayan tərtibatçı. Əlavə edilmiş package.json, docker-compose.yml və skriptlər/qovluq əsasında Məqsəd, Tələblər, Quraşdırma, Əməliyyat, Test, Töhfə bölmələri ilə README qaralama yazın. Bu fayllardan əmrləri çıxarın, onların heç bir yerində olmadığına əmin olmayın [VƏR]."
Güclü versiya tamaşaçıya, mənbəyə, struktura və “bunu et, qeyd et” qaydasını verir; belə ki, sənəd real fayllara əsaslanır və yoxlanılacaq yerlər aydın görünsün.
Sənəd növü
AI yaxşı işləyir
İnsan əlavə edir/təsdiq edir
README quraşdırılması
addım kontur
Addımları yerinə yetirin və təsdiqləyin
Docstring/API
Struktur, parametr, tip
Düzgün növ və "niyə"
Kod şərhi
"O nə edir" xülasəsi
"Niyə belədir" əsaslandırması
Changelog/PR
ilk qaralama
Təsir və dəqiqlik
Memarlıq qərarı (ADR)
skelet
Həqiqi qərarlar və kompromislər
Sənədlər Baxım Tələb edir
Sənədin ən təhlükəli tərəfi onun yalan olmasına baxmayaraq doğru görünməsidir. Kod dəyişdikdə və sənəd yenilənmədikdə, oxucunu aktiv şəkildə çaşdırır. AI yeniləməni asanlaşdırır: fərq verin və “bu dəyişiklik sənədin hansı hissələrinə təsir edir?” sualını verin. soruşa bilərsiniz. Lakin bu, aktuallığı təmin edən prosesdir — sənədlərin yenilənməsini kod dəyişikliyinin bir hissəsi edin (PR-nin qəbul meyarı). AI sürətləndirir; Komanda nizam-intizam qurur.
Diqqət: README-də quraşdırma addımlarını yoxlamadan dərc etməyin. "Yəqin ki, iş" sənədi yeni tərtibatçının ilk gününü məhv edə və etibarını itirə bilər. Təmiz bir mühitdə addımları özünüz aparın.
Ümumi səhvlər
- Süni intellektə uyğunlaşmaq üçün “niyə” əldə etmək. Yalançı bəraət bəraət qazandırmamaqdan daha pisdir; Kod sahibi dizayn səbəbini yazmalıdır.
- Quraşdırma addımlarının yoxlanılması. İşləməyən README inamı məhv edir.
- Kodu təkrarlayan lazımsız şərh. O, səs-küy yaradır, real "niyə" şərhlərini gizlədir.
- Hədəf auditoriyasının müəyyən edilməməsi. Kimə yazıldığı aydın olmayan sənədin nə yeni başlayana, nə də ekspertə faydası yoxdur.
- Yeniləmənin prosesdən ayrılması. Sənəd kodla yenilənməzsə, o, tez bir zamanda yanıltıcı olur.
Xülasə
Süni intellekt mexaniki yükün çox hissəsini sənədlərdən götürür: sürətli README, docstring, API arayışı, dəyişiklik jurnalı və PR təsvirləri. Amma ən qiymətli təbəqə olan “niyə”ni bilə bilməz və onu uydurmaq təhlükəlidir. Əmək bölgüsü aydındır: AI “nə/necə” istehsal edir, siz “niyə” əlavə edirsiniz. Auditoriyanı göstərin, resursları təmin edin, struktur tətbiq edin, uyğun yerləri qeyd edin və hər quraşdırma addımını özünüz işə salmaqla yoxlayın. Sənədləri kod dəyişikliyinin ayrılmaz hissəsinə çevirin.
Tətbiq tapşırığı
Sənədləri çatışmayan və ya köhnəlmiş modul və ya kiçik layihə seçin. Əvvəlcə “strukturlaşdırılmış README layihəsi” (və ya docstring) şablonu ilə AI-dən kontur yaradın; Mənbəni və hədəf auditoriyanı verdiyinizə əmin olun. Sonra süni intellektin [DOĞRULA] və ya [NİYƏ LAZIMDIR] qeyd etdiyi hər bir nöqtədən keçin: əslində quraşdırma addımlarını yerinə yetirin və öz biliyinizlə dizaynı "niyə" doldurun. Neçə addımın düzəldilməli olduğunu və neçə "niyə" əlavə etdiyinizi qeyd edin.
yoxlama siyahısı
- [ ] Sənədlərdə mən "nə/necə" və "niyə" qatlarını fərqləndirirəm.
- [ ] Mən süni intellektdən "niyə"ni təşkil etmirəm, onu özüm əlavə edirəm.
- [ ] Mən sorğuya hədəf auditoriyanı və faktiki mənbə fayllarını verirəm.
- [ ] Mən AI tərəfindən qeyd olunan [DOĞRULA] nöqtələrini şəxsən yerinə yetirməklə yoxlayıram.
- [ ] Kodu təkrarlayan lazımsız şərhləri aradan qaldırıram.
- [ ] Sənədlərin yenilənməsini kod dəyişikliyinin bir hissəsi edirəm.