Добивки:
- Способност да се произведуваат нацрти README, стрингови и дневници за промени врз основа на целната публика и изворот со вештачка интелигенција
- Способност да се одделат слоевите „што/како“ и „зошто“ во документацијата и да се додаде „зошто“ како човек
- Потврдете ги чекорите за инсталација со тоа што лично ќе ги извршите и ќе го направите документот дел од промената на кодот
Најчесто занемаруваниот, но најдолготрајниот дел од софтверот е документацијата. Кодот е читлив дури и по месеци; Тој што го напиша го нема, контекстот е заборавен, а остана само напишаното. Добар README (воведен документ кој објаснува што е проект и како да го инсталирате и стартувате), коментари за објаснување на кодот и ажурирана документација за API (референца што објаснува како да се користи интерфејс) директно ја одредува брзината на тимот. Вештачката интелигенција одзема голем дел од „заморот од пишувањето“ од документацијата - но доаѓа со замка: вештачката интелигенција може да заклучи од кодот што прави, но честопати не може да знае зошто е направено на тој начин.
Во оваа единица, ќе научите како да произведувате README, коментар на код, документарец (коментари напишан по функција/класа), документ API и дневник за промени со вештачка интелигенција; и како човечки да се зачува највредниот дел од документацијата: „зошто“.
Разлика помеѓу „Што“ и „Зошто“
Постојат два слоја на документација. Првиот е што/како: „оваа функција подредува листа“, „изврши ја оваа команда за инсталирање“. Тие можат да се извлечат од кодот и структурата; Вештачката интелигенција се истакнува овде. Второ, зошто: „зошто ја направивме оваа услуга асинхрона наместо синхрона“, „зошто оваа гранична вредност е 30 секунди“, „зошто ја избравме оваа библиотека пред другата“. Овие не се напишани во кодот; Тоа е производ на дизајнерски одлуки, ограничувања и минати болки.
ВИ не знае „зошто“; Во најдобар случај, тоа прави разумна претпоставка - што е опасно, бидејќи погрешната причина е полоша отколку да нема никаква причина. Значи, поделбата на работата е јасна: ВИ го подготвува „што/како“, а вие додавате „зошто“. Највредниот коментар е оној што го кажува она што кодот не може да го каже.
Совет: Не повторувајте со коментар што јасно го кажува самиот код (како i = i + 1 // зголемете i за еден). ВИ понекогаш произведува такви непотребни коментари; Елиминирајте ги и посветете ја вашата енергија на коментарите „зошто“.
Чекор по чекор: генерирање документација со вештачка интелигенција
- Наведете ја целната публика. „Програмер кој штотуку започнува“, „надворешниот тим што ќе го користи ова API“, „идниот јас“ - публиката го поставува тонот за јазикот и длабочината.
- Наведете го изворот. Додајте го релевантниот код, постоечкиот README, примерот за употреба во промптот. Документ без извор е покана за изработка.
- Структура на наметнување. Стандардни делови за README (цел, инсталација, употреба, конфигурација, придонес), проектен формат за docstring.
- Обележете ги празнините „зошто“. Побарајте од вештачката интелигенција да ги означи одлуките за кои не го знае образложението како „тука е потребна белешка „зошто“; Потоа ги пополнувате тие празни места.
- Потврди. Всушност, извршете ги чекорите за инсталација; пробајте го примерокот на кодот. README што не работи е полошо отколку воопшто да не README.
Три мини футроли
Случај 1 - README го забрза влегувањето. Недостигаше README на алатката со отворен код; Новите соработници се мачеа со инсталацијата во просек 2 часа. Тимот ги даде инсталационите скрипти и package.json на вештачката интелигенција и подготви структуриран README, а потоа самиот ги изврши чекорите на чиста машина и ги додаде двете зависности што недостасуваа. Времето на инсталација за следните соработници се намали во просек на 25 минути.
Случај 2 - Измислената стапица „зошто“. Еден развивач побара од AI коментар до вредноста на истек на време (тајмаут=30). Вештачката интелигенција напиша разумно, но неточно оправдување „да се толерира висока латентност на мрежата“; вистинската причина беше договорниот лимит од 30 секунди на надолната услуга. Погрешното толкување го наведе последователниот развивач непотребно да ја зголеми вредноста, што доведе до инцидент. Поука: сопственикот на кодот мора да го потврди оправдувањето.
Случај 3 - Стандардот Docstring стана автоматизиран. Помошен модул со 40 функции немаше стрингови за документи. На вештачката интелигенција му беше даден проектен формат (стил на Google) и произведе описи на параметри, враќање и исклучоци за секоја функција; Програмерот ги разгледа овие и поправи неколку декларации за неточни типови. Документирањето на 40 функции се намали од околу половина ден на еден час.
Четири шаблони за копирање
Структуриран нацрт README:
Целна публика: {{на пр. нов соработник}}. Напишете нацрт README врз основа на датотеките подолу. Секции: Цел, Карактеристики, Барања, Инсталација, Операција, Конфигурација, Тестирање, Придонес. Извадете ги командите за инсталација/извршување од вистинските датотеки; МОТВАЊЕ. Обележете ги местата за кои не сте сигурни со „[VERIFY]“. Извор: {{package.json / скрипти / примерок код}}
Референца за Docstring/API:
Напишете стринг за овие функции во формат {{проектен стил: Google/NumPy/JSDoc}}: кратко резиме, параметри (тип + значење), враќање, исклучоци исклучоци, 1 краток пример. Не го повторувајте она што ЈАСНО го кажува кодот. Обележете ги решенијата за дизајн што бараат „зошто“ како „[ЗОШТО ПОТРЕБНО]“, не пишувајте измислено оправдување.{{ код}}
Отстранете ги празните места за коментарот „зошто“:
Во овој код, следниот развивач може да праша "зошто е тоа така?" (магични бројки, необични одлуки, решенија). Дајте коментар СКЕЛЕТ за секој, но оставете го образложението ПРАЗНО; Ќе го пополнам оправдувањето.{{шифра}}
Изјава за промени/ПР:
Напишете {{запис за промени во дневникот / опис на односи со јавноста}} од разликата подолу. Формат: Што се смени (на јазикот на корисникот), Зошто (прашање: {{...}}), Прекината промена (ако има), Дали е тестирана. Приспособете го техничкиот жаргон на целната публика.{{разлика}}
Слаб промпт / Силен промпт
Слаб: „Напишете README за овој проект“.
Силно: „Целна публика: програмер што го клонира ова репо за прв пат. Врз основа на приложениот пакет.json, docker-compose.yml и фолдерот scripts/, напишете нацрт README со секциите Цел, Барања, Инсталација, Операција, Тестирање, Придонес. Извлечете ги командите од овие датотеки, ДА не ги означувате [АКО не сте сигурни] со некои датотеки.
Силната верзија ѝ дава на публиката, изворот, структурата и правилото „направи, означи го“; така што документот се базира на вистински досиеја и местата што треба да се проверат се јасно видливи.
Тип на документ
ВИ е добро
Човекот додава/проверува
README инсталација
преглед на чекор
Извршете ги чекорите и потврдете
Docstring/API
Структура, параметар, тип
Точен тип и „зошто“
Коментар на кодот
Резиме „Што прави тој“.
„Зошто е ова“ оправдување
Промена/ПР
првиот нацрт
Влијание и точност
Архитектонска одлука (АДР)
скелет
Вистински одлуки и компромиси
Документацијата бара одржување
Најопасниот аспект на документот е кога се чини дека е вистинит иако е лажен. Кога кодот се менува и документот не се ажурира, тој активно го доведува читателот во заблуда. Вештачката интелигенција го олеснува ажурирањето: издадете разлика и прашајте „на кои делови од документот влијае оваа промена? може да прашате. Но, процесот е тој што обезбедува ажурирање - направете го ажурирањето на документацијата дел од промената на кодот (критериум за прифаќање на ПР). ВИ забрзува; Тимот гради дисциплина.
Внимание: Не објавувајте без да ги потврдите чекорите за инсталација во README. Документот „веројатно работен“ може да го уништи првиот ден на новиот програмер и да ја уништи довербата. Испратете ги чекорите сами во чиста средина.
Вообичаени грешки
- Добивање на „зошто“ да одговара на вештачката интелигенција. Лажното оправдување е полошо од неоправдувањето; Сопственикот на кодот треба да ја напише причината за дизајнот.
- Не се потврдуваат чекорите за инсталација. README што не функционира ја уништува довербата.
- Непотребен коментар со повторување на кодот. Тоа произведува бучава, прикривајќи ги вистинските интерпретации „зошто“.
- Не наведувајќи ја целната публика. Документ што е нејасно кому му е напишан не му користи ниту на почетникот ниту на експертот.
- Одвојување на ажурирањето од процесот. Ако документот не се ажурира со кодот, тој брзо станува погрешен.
Сумирано
Вештачката интелигенција презема голем дел од механичкиот товар од документацијата: брзи нацрти README, docstring, референца на API, дневници за промени и описи за односи со јавноста. Но, не може да го знае „зошто“, што е највредниот слој, и опасно е да се состави. Поделбата на трудот е јасна: вештачката интелигенција произведува „што/како“, вие додавате „зошто“. Наведете ја публиката, обезбедете ресурси, наметнете структура, означете ги местата што треба да се вклопат и потврдете го секој чекор на инсталација така што ќе го извршите сами. Документацијата нека биде составен дел од промената на кодот.
Задача за апликација
Изберете модул или мал проект чија документација недостасува или е застарена. Прво генерирајте преглед од вештачката интелигенција со шаблонот „структуриран нацрт README“ (или докстринг); Бидете сигурни да ги дадете изворот и целната публика. Потоа поминете низ секоја точка каде што вештачката интелигенција има означено [VERIFY] или [ZHY EDED]: всушност извршете ги чекорите за поставување и пополнете го дизајнот „зошто“ со сопствено знаење. Забележете колку чекори треба да се поправат и колку „зошто“ сте додале.
листа за проверка
- [ ] Во документацијата ги разликувам слоевите „што/како“ и „зошто“.
- [ ] Јас не ја правам вештачката интелигенција да го сочинува „зошто“, го додавам сам.
- [ ] На барањето му ја давам целната публика и вистинските изворни датотеки.
- [ ] Ги проверувам точките [VERIFY] означени со вештачката интелигенција со нивно лично извршување.
- [ ] Ги елиминирам непотребните коментари кои го повторуваат кодот.
- [ ] Ажурирањето на документацијата го правам дел од промената на кодот.