Добици:
- Способност израде нацрта РЕАДМЕ, доцстринг и дневника промена на основу циљне публике и извора са АИ
- Способност одвајања слојева „шта/како“ и „зашто“ у документацији и додавања „зашто“ као човека
- Провера корака инсталације тако што ћете их лично покренути и учинити документ делом промене кода
Најчешћи занемарени, али најдуготрајнији део софтвера је документација. Код је читљив чак и након неколико месеци; Отишла је особа која је то написала, контекст је заборављен, а остало је само оно што је написано. Добар РЕАДМЕ (уводни документ који објашњава шта је пројекат и како да га инсталирате и покренете), коментари кода са објашњењима и ажурна АПИ документација (референца која објашњава како се користи интерфејс) директно одређује брзину тима. АИ уклања много „замора од писања“ из документације — али долази са замком: АИ може закључити из кода шта ради, али често не може знати зашто се то ради на тај начин.
У овој јединици ћете научити како да направите РЕАДМЕ, коментар кода, доцстринг (блок коментара написан по функцији/класи), АПИ документ и дневник промена са АИ; и како људски сачувати највреднији део документације: „зашто“.
Разлика између "шта" и "зашто"
Постоје два слоја документације. Прво је шта/како: "ова функција сортира листу", "покрените ову команду за инсталацију". Они се могу издвојити из кода и структуре; АИ се овде истиче. Друго, зашто: „зашто смо ову услугу учинили асинхроном, а не синхроном“, „зашто је ова гранична вредност 30 секунди“, „зашто смо изабрали ову библиотеку у односу на другу“. Ово није записано у коду; То је производ дизајнерских одлука, ограничења и прошлих болова.
АИ не зна "зашто"; У најбољем случају, то чини разумну претпоставку - што је опасно, јер је погрешан разлог гори од никаквог разлога. Дакле, подела рада је јасна: АИ саставља „шта/како“, ви додајете „зашто“. Највреднији коментар је онај који каже оно што код не може да каже.
Савет: Не понављајте коментаром оно што сам код јасно каже (као и = и + 1 // повећајте и за један). АИ понекад производи такве сувишне коментаре; Елиминишите их и посветите своју енергију коментарима „зашто“.
Корак по корак: генерисање документације помоћу вештачке интелигенције
- Наведите циљну публику. „Програмер који тек почиње“, „спољни тим који ће користити овај АПИ“, „ја будућност“ — публика поставља тон за језик и дубину.
- Дајте извор. Додајте одговарајући код, постојећи РЕАДМЕ, пример употребе у промпт. Документ без извора је позив на фабриковање.
- Структура наметања. Стандардни одељци за РЕАДМЕ (Сврха, Инсталација, Употреба, Конфигурација, Допринос), формат пројекта за доцстринг.
- Означите размаке „зашто“. Замолите АИ да означи одлуке за које не зна образложење као „овде је потребна напомена 'зашто'“; Затим попуните те празнине.
- Верифи. Заправо покрените кораке инсталације; пробајте узорак кода. РЕАДМЕ који не ради је гори од тога да уопште не ради.
Три мини кућишта
Случај 1 — РЕАДМЕ убрзано укључивање. Недостајао је РЕАДМЕ алата отвореног кода; Нови сарадници су се мучили са инсталацијом у просеку 2 сата. Тим је дао инсталационе скрипте и пацкаге.јсон АИ и направио структурирани РЕАДМЕ, а затим је покренуо саме кораке на чистој машини и додао две недостајуће зависности. Време инсталације за следеће сараднике се смањило на просечно 25 минута.
Случај 2 — Измишљена замка „зашто“. Програмер је тражио од АИ коментар поред вредности временског ограничења (временско ограничење=30). АИ је написао разумно, али нетачно оправдање „да се толерише велико кашњење мреже“; прави разлог је било уговорно ограничење од 30 секунди низводне услуге. Погрешно тумачење навело је накнадног програмера да непотребно повећа вредност, што је довело до инцидента. Поука: власник кода мора да провери оправданост.
Случај 3 — Доцстринг стандард је постао аутоматизован. Помоћни модул са 40 функција није имао низове докумената. АИ је добио формат пројекта (Гоогле стил) и произвео описе параметара, повратка и изузетака за сваку функцију; Програмер их је прегледао и поправио неколико нетачних декларација типа. Документовање 40 функција се смањило са отприлике пола дана на сат времена.
Четири шаблона за копирање
Структурирана верзија РЕАДМЕ:
Циљна публика: {{нпр. нови сарадник}}. Напишите нацрт РЕАДМЕ-а на основу датотека испод. Одељци: сврха, карактеристике, захтеви, инсталација, рад, конфигурација, тестирање, допринос. Издвојите команде за инсталацију/покретање из стварних датотека; ФИТТИНГ. Означите места за која нисте сигурни са „[ВЕРИФИ]“. Извор: {{пацкаге.јсон / сцриптс / сампле цоде}}
Референца за стринг докумената/АПИ:
Напишите доцстринг за ове функције у формату {{пројецт стиле: Гоогле/НумПи/ЈСДоц}}: кратак резиме, параметри (тип + значење), повратак, изузеци, 1 кратак пример. Не понављајте оно што код ЈАСНО каже. Означите одлуке о дизајну које захтевају „зашто“ као „[ЗАШТО ПОТРЕБНО]“, немојте писати измишљено оправдање.{{цоде}}
Уклоните размаке за коментар „зашто“:
У овом коду, следећи програмер би могао да пита "зашто је то тако?" (магични бројеви, необичне одлуке, заобилазна решења). Дајте коментар СКЕЛЕТ за сваку, али оставите образложење ПРАЗНО; Попунићу образложење.{{цоде}}
Дневник промена/ПР изјава:
Напишите {{унос измена / ПР опис}} из разлике испод. Формат: Шта се променило (на корисничком језику), Зашто (проблем: {{...}}), Прекидна промена (ако постоји), Да ли је тестирано. Прилагодите технички жаргон циљној публици.{{дифф}}
Слаби промпт / Јаки промпт
Слабо: „Напишите РЕАДМЕ за овај пројекат.“
Снажно: „Циљна публика: програмер који клонира овај репо по први пут. На основу приложеног пацкаге.јсон, доцкер-цомпосе.имл и фасцикле сцриптс/, напишите нацрт РЕАДМЕ-а са одељцима „Сврха“, „Захтеви“, „Инсталација“, „Операција“, „Тестирање“, „Допринос. Извуците команде из ових датотека, немојте их измишљати; немојте сигурно да их измислите; означите било где“.
Јака верзија даје публику, извор, структуру и правило „направи, означи“; тако да је документ заснован на стварним фајловима и да су места која се верификује јасно видљива.
Врста документа
АИ ради добро
Човек додаје/верификује
РЕАДМЕ инсталација
обрис корака
Покрените кораке и потврдите
Доцстринг/АПИ
Структура, параметар, тип
Тачан тип и "зашто"
Коментар кода
Резиме „Шта ради“.
„Зашто је ово“ оправдање
Дневник промена/ПР
први нацрт
Утицај и тачност
Архитектонска одлука (АДР)
скелет
Праве одлуке и компромиси
Документација захтева одржавање
Најопаснији аспект документа је када се чини истинитим иако је лажан. Када се код промени, а документ се не ажурира, он активно обмањује читаоца. АИ олакшава ажурирање: издајте дифф и питајте „на које делове документа утиче ова промена?“ можете питати. Али то је процес који обезбеђује ажурност — нека ажурирање документације буде део промене кода (критеријум прихватања ПР-а). АИ убрзава; Тим гради дисциплину.
Опрез: Немојте објављивати без провере корака инсталације у РЕАДМЕ-у. Документ „вероватно ради“ може упропастити први дан новог програмера и нарушити поверење. Покрените кораке сами у чистом окружењу.
Уобичајене грешке
- Добијање „зашто“ да одговара АИ. Лажно оправдање је горе од никаквог оправдања; Власник кода треба да напише разлог дизајна.
- Не проверавамо кораке инсталације. РЕАДМЕ који не ради уништава поверење.
- Непотребан коментар који понавља код. Производи буку, замагљујући права тумачења „зашто“.
- Не наводећи циљну публику. Документ за који је нејасно коме је написан није од користи ни почетнику ни стручњаку.
- Одвајање ажурирања од процеса. Ако документ није ажуриран кодом, брзо постаје погрешан.
Укратко
АИ преузима велики део механичког терета из документације: брзи нацрти РЕАДМЕ, доцстринг, АПИ референце, дневник промена и ПР описи. Али оно не може да зна „зашто“, који је највреднији слој, и опасно га је надокнадити. Подела рада је јасна: АИ производи „шта/како“, ви додајете „зашто“. Одредите публику, обезбедите ресурсе, наметните структуру, означите места која се уклапају и проверите сваки корак инсталације тако што ћете га сами покренути. Учините документацију саставним делом промене кода.
Задатак апликације
Изаберите модул или мали пројекат чија документација недостаје или је застарела. Прво генеришите нацрт из АИ са шаблоном „структурирани РЕАДМЕ нацрт“ (или доцстринг); Обавезно наведите извор и циљну публику. Затим прођите кроз сваку тачку где је АИ означио [ВЕРИФИ] или [ЗАШТО ТРЕБА]: заправо покрените кораке подешавања и попуните дизајн „зашто“ сопственим знањем. Забележите колико корака треба да се поправи и колико „зашто“ сте додали.
контролна листа
- [ ] У документацији разликујем слојеве „шта/како“ и „зашто“.
- [ ] Не правим да вештачка интелигенција измишља „зашто“, ја то сам додајем.
- [ ] Дајем упиту циљну публику и стварне изворне датотеке.
- [ ] Проверавам [ВЕРИФИ] тачке које је означила АИ тако што их лично извршавам.
- [ ] Елиминишем непотребне коментаре који понављају код.
- [ ] Ажурирање документације чиним делом промене кода.