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