Печалби:
- Възможност за създаване на README, docstring и чернови на регистър на промените въз основа на целевата аудитория и източник с AI
- Възможност за разделяне на слоевете „какво/как“ и „защо“ в документацията и добавяне на „защо“ като човек
- Проверка на стъпките за инсталиране, като ги стартирате лично и направите документа част от промяната на кода
Най-често пренебрегваната, но най-дълготрайна част от софтуера е документацията. Кодът се чете дори след месеци; Човекът, който го е написал, го няма, контекстът е забравен и остава само написаното. Един добър README (въвеждащ документ, който обяснява какво е проект и как да го инсталирате и изпълнявате), обяснителни коментари на кода и актуална API документация (препратка, която обяснява как да използвате интерфейс) директно определя скоростта на екипа. AI премахва голяма част от „умората при писане“ от документацията — но идва с капан: AI може да заключи от кода какво прави, но често не може да знае защо се прави по този начин.
В този модул ще научите как да създавате README, коментар на кода, docstring (блок за коментари, написан за функция/клас), API документ и регистър на промените с AI; и как по човешки да запазим най-ценната част от документацията: „защо“.
Разграничение между "Какво" и "Защо"
Има два слоя документация. Първият е какво/как: "тази функция сортира списък", "изпълнете тази команда за инсталиране". Те могат да бъдат извлечени от кода и структурата; AI превъзхожда тук. Второ, защо: „защо направихме тази услуга асинхронна, а не синхронна“, „защо тази лимитна стойност е 30 секунди“, „защо избрахме тази библиотека пред другата“. Те не са записани в кода; Това е продукт на дизайнерски решения, ограничения и минала болка.
AI не знае "защо"; В най-добрия случай прави разумно предположение - което е опасно, защото грешната причина е по-лоша от липсата на причина. Така че разделението на труда е ясно: AI чертае „какво/как“, вие добавяте „защо“. Най-ценният коментар е този, който казва това, което кодът не може да каже.
Съвет: Не повтаряйте с коментар това, което самият код ясно казва (като i = i + 1 // увеличаване на i с едно). AI понякога произвежда такива излишни коментари; Елиминирайте ги и посветете енергията си на коментари „защо“.
Стъпка по стъпка: Генериране на документация с AI
- Посочете целевата аудитория. „Програмист, който току-що започва“, „външният екип, който ще използва този API“, „бъдещият аз“ — публиката задава тона за език и дълбочина.
- Дайте източника. Добавете съответния код, съществуващ README, примерна употреба към подканата. Документ без източник е покана за фабрикуване.
- Структура на налагането. Стандартни секции за README (Цел, Инсталиране, Използване, Конфигурация, Принос), формат на проекта за docstring.
- Маркирайте интервалите „защо“. Помолете ИИ да маркира решения, за които не знае обосновката като „тук се изисква бележка „защо““; След това попълвате тези празни места.
- Проверете. Действително стартирайте стъпките за инсталиране; опитайте примерния код. README, който не работи, е по-лош от липсата на README.
Три мини калъфа
Случай 1 — README ускорено включване. README на инструмент с отворен код липсваше; Новите участници се бориха с инсталацията средно 2 часа. Екипът даде инсталационните скриптове и package.json на AI и изготви структуриран README, след което изпълни самите стъпки на чиста машина и добави двете липсващи зависимости. Времето за инсталиране за следващите сътрудници намаля до средно 25 минути.
Случай 2 — Измисленият капан „защо“. Разработчик помоли AI за коментар до стойността на изчакване (timeout=30). AI написа разумна, но неправилна обосновка „да толерира висока латентност на мрежата“; истинската причина беше договореното ограничение от 30 секунди на услугата надолу по веригата. Погрешното тълкуване накара последващ разработчик да увеличи ненужно стойността, което доведе до инцидент. Урок: собственикът на кода трябва да провери обосновката.
Случай 3 — Стандартът Docstring стана автоматизиран. Помощен модул с 40 функции нямаше документационни низове. На AI беше даден формат на проекта (стил на Google) и произведени описания на параметри, връщане и изключения за всяка функция; Разработчикът ги прегледа и поправи няколко неправилни декларации за тип. Документирането на 40 функции намаля от около половин ден на час.
Четири копируеми шаблона
Структурирана чернова README:
Целева аудитория: {{напр. нов сътрудник}}.Напишете проект на README въз основа на файловете по-долу. Раздели: Цел, Характеристики, Изисквания, Инсталация, Работа, Конфигурация, Тестване, Принос. Извличане на команди за инсталиране/изпълнение от действителни файлове; МОНТАЖ. Маркирайте местата, за които не сте сигурни с „[ПОТВЪРЖДАВАНЕ]“. Източник: {{package.json / скриптове / примерен код}}
Справка за Docstring/API:
Напишете docstring към тези функции във формат {{project style: Google/NumPy/JSDoc}}: кратко резюме, параметри (тип + значение), връщане, хвърлени изключения, 1 кратък пример. Не повтаряйте това, което кодът казва ЯСНО. Маркирайте дизайнерски решения, които изискват „защо“ като „[ЗАЩО Е НЕОБХОДИМО]“, не пишете измислена обосновка.{{code}}
Премахнете интервалите за коментар „защо“:
В този код следващият разработчик може да попита "защо е така?" (магически числа, необичайни решения, заобиколни решения). Дайте коментар СКЕЛЕТ за всеки, но оставете обосновката ПРАЗНА; Ще попълня обосновката.{{code}}
Списък на промените/PR изявление:
Напишете {{changelog запис / PR описание}} от разликата по-долу. Формат: Какво се промени (на езика на потребителя), Защо (проблем: {{...}}), Критична промяна (ако има такава), Тествано ли е. Приспособете техническия жаргон към целевата аудитория.{{diff}}
Слаба подкана / Силна подкана
Слаб: „Напишете README за този проект.“
Силно: „Целева аудитория: разработчик, който клонира това репо за първи път. Въз основа на прикачените package.json, docker-compose.yml и папка scripts/, напишете чернова README със секции за цел, изисквания, инсталация, работа, тестване, принос. Извлечете командите от тези файлове, не ги измисляйте; маркирайте навсякъде, където не сте сигурни, с [VERIFY].“
Силната версия дава публиката, източника, структурата и правилото „направи го, отбележи го“; така че документът да се основава на реални файлове и местата, които трябва да бъдат проверени, са ясно видими.
Тип документ
AI се справя добре
Човек добавя/потвърждава
README инсталация
стъпка контур
Изпълнете стъпките и потвърдете
Docstring/API
Структура, параметър, тип
Правилен тип и "защо"
Коментар на кода
Резюме „Какво прави“.
"Защо е това" оправдание
Списък на промените/PR
първа чернова
Въздействие и точност
Архитектурно решение (ADR)
скелет
Реални решения и компромиси
Документацията изисква поддръжка
Най-опасният аспект на един документ е, когато изглежда верен, въпреки че е фалшив. Когато кодът се промени и документът не се актуализира, това активно подвежда читателя. AI прави актуализирането лесно: издайте diff и попитайте „кои части от документа засяга тази промяна?“ може да попитате. Но това е процесът, който гарантира актуалност — направете актуализацията на документацията част от промяната на кода (критерият за приемане на PR). AI ускорява; Екипът изгражда дисциплина.
Внимание: Не публикувайте, без да проверите стъпките за инсталиране в README. „Вероятно работен“ документ може да съсипе първия ден на нов разработчик и да подкопае доверието. Изпълнете стъпките сами в чиста среда.
Често срещани грешки
- Получаване на „защо“, за да пасне на AI. Фалшивото оправдание е по-лошо от липсата на оправдание; Собственикът на кода трябва да напише причината за дизайна.
- Не се проверяват стъпките за инсталиране. README, който не работи, разрушава доверието.
- Ненужен коментар, повтарящ кода. Той произвежда шум, замъглявайки истинските интерпретации на „защо“.
- Без уточняване на целевата аудитория. Документ, който не е ясно за кого е написан, не е полезен нито за начинаещия, нито за експерта.
- Разделяне на актуализацията от процеса. Ако документът не е актуализиран с кода, той бързо става подвеждащ.
В обобщение
AI поема голяма част от механичната тежест на документацията: бързи чернови README, docstring, препратка към API, регистър на промените и PR описания. Но то не може да знае „защо“, което е най-ценният пласт, и е опасно да го измисляме. Разделението на труда е ясно: AI произвежда „какво/как“, вие добавяте „защо“. Посочете аудиторията, осигурете ресурси, наложете структура, маркирайте места, които да паснат, и проверете всяка стъпка на инсталиране, като я стартирате сами. Направете документацията неразделна част от промяната на кода.
Задача за приложение
Изберете модул или малък проект, чиято документация липсва или е остаряла. Първо генерирайте схема от AI с шаблона „структуриран проект на README“ (или docstring); Не забравяйте да посочите източника и целевата аудитория. След това преминете през всяка точка, където AI е маркирал [VERIFY] или [WHY NEEDED]: всъщност изпълнете стъпките за настройка и попълнете дизайна „защо“ със собствените си знания. Отбележете колко стъпки трябва да бъдат коригирани и колко „защо“ сте добавили.
контролен списък
- [ ] В документацията различавам слоевете „какво/как“ и „защо“.
- [ ] Не карам AI да измисля „защо“, добавям го сам.
- [ ] Давам на подканата целевата аудитория и действителните изходни файлове.
- [ ] Проверявам точките [VERIFY], маркирани от AI, като ги изпълнявам лично.
- [ ] Премахвам ненужните коментари, които повтарят кода.
- [ ] Правя актуализацията на документацията част от промяната на кода.