Пайдалар:
- Максаттуу аудиторияга жана AI менен булакка негизделген README, докстринг жана өзгөртүүлөр журналынын долбоорлорун чыгаруу мүмкүнчүлүгү
- Документте "эмне/кантип" жана "эмне үчүн" катмарларын бөлүп, адам катары "эмне үчүн" кошуу мүмкүнчүлүгү
- Орнотуу кадамдарын жеке өзү иштетип, документти кодду өзгөртүүнүн бир бөлүгү кылып текшерүү
Эң көп көңүл бурулбай калган, бирок программалык камсыздоонун эң узакка созулган бөлүгү бул документация. Код ай өткөндөн кийин да окулат; Аны жазган адам жок, контекст унутулуп, жазылганы гана калды. Жакшы README (долбоор деген эмне экенин жана аны кантип орнотуу жана иштетүүнү түшүндүрүүчү киришүү документи), түшүндүрмө коддук комментарийлер жана заманбап API документтери (интерфейсти кантип колдонууну түшүндүргөн маалымдама) команданын ылдамдыгын түздөн-түз аныктайт. AI документациядан "жазуудан чарчагандын" көп бөлүгүн алат — бирок ал капкан менен коштолот: AI коддон эмне кылып жатканын тыянак чыгара алат, бирок көбүнчө эмне үчүн мындай жасалганын биле албайт.
Бул бөлүмдө сиз AI менен README, код комментарийин, докстрингди (функцияга/класска жазылган комментарий блогун), API документин жана өзгөртүү журналын кантип чыгарууну үйрөнөсүз; жана документациянын эң баалуу бөлүгүн адамдык түрдө кантип сактоо керек: "эмне үчүн".
"Эмне" жана "Эмне үчүн" ортосундагы айырма
Документтин эки катмары бар. Биринчиси эмне/кантип: "бул функция тизмени иреттейт", "орнотуу үчүн бул буйрукту иштет". Буларды коддон жана структурадан чыгарууга болот; Бул жерде AI мыкты. Экинчиден, эмне үчүн: "эмне үчүн биз бул кызматты синхрондук эмес, асинхрондук кылдык", "эмне үчүн бул чектүү 30 секунд", "эмне үчүн биз бул китепкананы экинчисинен тандап алдык". Булар коддо жазылган эмес; Бул долбоорлоо чечимдеринин, чектөөлөрдүн жана өткөн азаптын натыйжасы.
AI "эмне үчүн" экенин билбейт; Эң жакшысы, бул жөндүү божомолду түзөт — бул кооптуу, анткени туура эмес себеп такыр себеп жоктон да жаман. Ошентип, эмгекти бөлүштүрүү түшүнүктүү: AI "эмне/кантип" долбоорун иштеп чыгат, сиз "эмне үчүн" дегенди кошосуз. Эң баалуу комментарий - бул код айта албаган нерсени айткан комментарий.
Кеңеш: Коддун өзү ачык айтылган нерсени комментарий менен кайталабаңыз (мисалы, i = i + 1 // i бирден көбөйтүү). AI кээде ушундай ашыкча комментарийлерди чыгарат; Аларды жок кылып, күчүңүздү "эмне үчүн" деген комментарийлерге арнаңыз.
Кадам кадам: AI менен документтерди түзүү
- Максаттуу аудиторияны көрсөтүңүз. "Жаңыдан баштап иштеп жаткан иштеп чыгуучу", "бул API колдоно турган тышкы команда", "келечектеги мен" — аудитория тил жана тереңдиктин обонун белгилейт.
- Булакты бер. Тиешелүү кодду, учурдагы READMEди, мисалды колдонууну эскертмеге кошуңуз. Булаксыз документ жасалмалоого чакыруу болуп саналат.
- Тактоо структурасы. README үчүн стандарттык бөлүмдөр (Максат, Орнотуу, Колдонуу, Конфигурация, Салым), документ стринг үчүн долбоордун форматы.
- "Эмне үчүн" боштуктарды белгилеңиз. AIдан жүйөсүн билбеген чечимдерди "бул жерде "эмне үчүн" эскертүүсү керек" деп белгилөөсүн сураныңыз; Анан ошол боштуктарды толтурасың.
- Текшерүү. Чындыгында орнотуу кадамдарын иштетиңиз; үлгү кодун аракет кыл. Иштебеген README такыр жок READMEден жаман.
Үч мини Case
1-жагдай — README тездетилген бортунда. Ачык булак куралынын README жок болчу; Жаңы салым кошкондор орто эсеп менен 2 саат орнотуу менен күрөшүштү. Команда орнотуу скрипттерин жана package.jsonди AIга берип, структураланган README долбоорун түздү, андан кийин кадамдарды өздөрү таза машинада иштетип, эки жетишпеген көз карандылыкты кошту. Кийинки салым кошкондор үчүн орнотуу убактысы орточо 25 мүнөткө чейин кыскарды.
2-жагдай - "Эмне үчүн" тузагы. Иштеп чыгуучу AIдан тайм-аут маанисинин жанында комментарий сурады (тайм-аут = 30). AI акылга сыярлык, бирок туура эмес негиздеме жазган "тармактын кечиктирилишине чыдаш үчүн"; чыныгы себеби ылдыйкы кызматтын келишимдик 30 секунддук чеги болгон. Туура эмес чечмелөө кийинки иштеп чыгуучунун маанисин негизсиз жогорулатууга алып келип, окуяга алып келди. Сабак: коддун ээси негиздемесин текшериши керек.
3-жагдай — Docstring стандарты автоматташтырылган. 40 функциясы бар көмөкчү модулда эч кандай документ саптары болгон эмес. AIге долбоордун форматы (Google стили) берилди жана ар бир функция үчүн параметр, кайтаруу жана өзгөчө жагдайлардын сүрөттөмөлөрү чыгарылды; Иштеп чыгуучу аларды карап чыгып, бир нече туура эмес түрдөгү декларацияларды оңдоду. 40 функцияны документтештирүү жарым күндөн бир саатка чейин кыскарды.
Көчүрмө төрт шаблон
Структураланган README долбоору:
Максаттуу аудитория: {{мис. new contributor}}.Төмөндөгү файлдардын негизинде README долбоорун жазыңыз. Бөлүмдөр: Максаты, өзгөчөлүктөрү, талаптары, орнотуу, иштетүү, конфигурациялоо, сыноо, салым. Иш жүзүндөгү файлдардан орнотуу/иштеп жаткан буйруктарды чыгарып алыңыз; ЖАРАШУУ. Сиз ишенбеген жерлерди "[ТЕКШЕРҮҮ]" менен белгилеңиз. Булак: {{package.json / скрипттер / үлгү код}}
Docstring/API шилтемеси:
Бул функцияларга {{долбоордун стили: Google/NumPy/JSDoc}} форматында докстринди жазыңыз: кыскача корутунду, параметрлер (түр + маани), кайтаруу, ташталган өзгөчөлүктөр, 1 кыска мисал. Код АЧЫК айткандарын кайталаба. "Эмне үчүн" талап кылынган дизайн чечимдерин "[ЭМНЕ ҮЧҮН КЕРЕК]" деп белгилеңиз, ойдон чыгарылган негиздеме жазбаңыз.{{code}}
"Эмне үчүн" жорумуна боштуктарды алып салыңыз:
Бул коддо кийинки иштеп чыгуучу "эмне үчүн мындай?" (сыйкырдуу сандар, адаттан тыш чечимдер, чечүү жолдору). Ар бирине комментарий бериңиз SKELETON, бирок жүйөөнү БУЛ калтырыңыз; Мен негиздемени толтурам.{{code}}
Changelog/PR билдирүүсү:
Төмөнкү айырмадан {{өзгөртүү жазуусу / PR сүрөттөмөсүн}} жазыңыз. Формат: Эмне өзгөрдү (колдонуучу тилинде), Эмне үчүн (маселе: {{...}}), үзгүлтүксүз өзгөртүү (эгер бар болсо), Ал текшерилгенби. Техникалык жаргонду максаттуу аудиторияга тууралаңыз.{{diff}}
Алсыз тездик / Күчтүү тездик
Алсыз: "Бул долбоор үчүн README жазыңыз."
Күчтүү: "Максаттуу аудитория: бул репо биринчи жолу клондогон иштеп чыгуучу. Тиркелген package.json, docker-compose.yml жана скрипттердин/ папканын негизинде, Максат, Талаптар, Орнотуу, Иштетүү, Сыноо, Салым бөлүмдөрү менен README долбоорун жазыңыз. Бул файлдардан буйруктарды чыгарып алыңыз, алардын эч бир жеринде эмес экенин белгилебеңиз, [Y] деп белгилебеңиз."
Күчтүү версия аудиторияга, булагын, структурасын жана "аны жаса, аны белгиле" эрежесин берет; Ошентип, документ чыныгы файлдарга негизделген жана текшериле турган жерлер даана көрүнүп турат.
Документтин түрү
AI жакшы кылат
Адам кошот/текшерет
README орнотуу
кадам схемасы
Кадамдарды аткарып, ырастаңыз
Docstring/API
Структура, параметр, түрү
Туура түрү жана "эмне үчүн"
Код комментарий
"Ал эмне кылып жатат" кыскача
"Эмне үчүн мындай" деген негиздеме
Changelog/PR
биринчи долбоор
Таасир жана тактык
Архитектуралык чечим (ADR)
скелет
Чыныгы чечимдер жана компромисстер
Документтер техникалык тейлөөнү талап кылат
Документтин эң кооптуу жагы – бул жалган болсо да чын болуп көрүнүүсү. Код өзгөрүп, документ жаңыланбаганда, ал окурманды активдүү адаштырууда. AI жаңыртууну жеңилдетет: айырманы чыгарып, “бул өзгөртүү документтин кайсы бөлүктөрүнө таасир этет?” деп сураңыз. деп сурасаңыз болот. Бирок бул процесс актуалдуулукту камсыздайт — документацияны жаңыртуу кодду өзгөртүүнүн бир бөлүгүн түзөт (PRдын кабыл алуу критерийи). AI ылдамдатат; Коллектив тартипти тузет.
Эскертүү: READMEдеги орнотуу кадамдарын текшербей туруп жарыялабаңыз. "Балким, иш" документи жаңы иштеп чыгуучунун биринчи күнүн бузуп, ишенимин кетириши мүмкүн. Кадамдарды таза чөйрөдө өзүңүз жүргүзүңүз.
Жалпы каталар
- AI ылайыктуу үчүн "эмне үчүн" алуу. Жалган актоо актабагандан да жаман; Коддун ээси дизайн себебин жазышы керек.
- Орнотуу кадамдары текшерилбейт. Иштебеген README ишенимди жок кылат.
- Кодду кайталаган керексиз комментарий. Ал ызы-чуу жаратып, чыныгы "эмне үчүн" деген интерпретацияларды жаап-жашырат.
- Максаттуу аудитория көрсөтүлгөн эмес. Кимге жазылганы түшүнүксүз документтин жаңы баштаганга да, экспертке да пайдасы жок.
- Жаңыртуу процессинен бөлүү. Документ код менен жаңыртылбаса, анда ал бат эле жаңылышат.
Кыскача айтканда
AI документтерден механикалык жүктүн көбүн алат: README тез долбоорлору, документ стринги, API маалымдамасы, өзгөртүүлөр журналы жана PR сүрөттөмөлөрү. Бирок эң баалуу катмар болгон «эмне үчүн» экенин биле албайт жана аны ойлоп чыгаруу коркунучтуу. Эмгекти бөлүштүрүү түшүнүктүү: AI "эмне/кантип" чыгарат, сиз "эмне үчүн" дегенди кошосуз. Аудиторияны көрсөтүңүз, ресурстар менен камсыз кылыңыз, структураны киргизиңиз, туура келген жерлерди белгилеңиз жана ар бир орнотуу кадамын өзүңүз иштетип текшериңиз. Документтерди кодду өзгөртүүнүн ажырагыс бөлүгүнө айландырыңыз.
Колдонмо тапшырмасы
Документтери жок же эскирген модулду же чакан долбоорду тандаңыз. Адегенде “структураланган README долбоору” (же докстринг) шаблону менен AIдан контур түзүңүз; Булакты жана максаттуу аудиторияны бериңиз. Андан кийин AI [ТЕКШЕРҮҮ] же [ЭМНЕ ҮЧҮН КЕРЕК] деп белгилеген ар бир чекиттен өтүңүз: чындыгында орнотуу кадамдарын аткарып, "эмне үчүн" дизайнын өз билимиңиз менен толтуруңуз. Канча кадамды оңдоо керек экенин жана канча "эмне үчүн" кошконуңузга көңүл буруңуз.
текшерүү тизмеси
- [ ] Документте мен "эмне/кантип" жана "эмне үчүн" катмарларын айырмалайм.
- [ ] Мен AI "эмне үчүн" дегенди түзбөйм, мен аны өзүм кошом.
- [ ] Мен максаттуу аудиторияга жана чыныгы булак файлдарын берем.
- [ ] AI белгилеген [ТЕКШЕРҮҮ] пункттарын жеке аткаруу менен текшерем.
- [ ] Мен кодду кайталаган керексиз комментарийлерди жок кылам.
- [ ] Мен документацияны жаңыртууну кодду өзгөртүүнүн бөлүгү кылып жатам.