Самодокументируемый код

Друзья, хочу раскрыть эту многогранную тему. С одной стороны это супер-привлекательная идея, представьте вы не тратите время на документацию, а просто соблюдаете некоторые правила при разработке. С другой стороны каждый разработчик в своей практике получал легаси, на которое он потратил пару ночей, чтобы разобраться. Рассмотрим плюсы и минусы:

Плюсы

Улучшенная читаемость: Код, который легко читается и понимается, сокращает время, необходимое для вникания в его работу, что особенно ценно для новых членов команды или при переходе к проекту после длительного перерыва.
Меньшая потребность в отдельной документации: Понятный код снижает необходимость в обширной внешней документации, так как назначение переменных, функций и классов очевидно из их имен и структуры кода.
Повышение производительности разработки: Когда код легко понять, разработчики могут быстрее вносить изменения и исправления, не тратя время на поиск и изучение внешней документации.
Упрощение поддержки и обновления: Самодокументируемый код облегчает обслуживание и обновление программного обеспечения, поскольку его логика и структура ясны без дополнительных пояснений.
Уменьшение вероятности ошибок: Четкое именование и структурирование кода помогают избегать недоразумений и ошибок при разработке, тестировании и последующих модификациях.
Облегчение рефакторинга: Ясный и понятный код легче рефакторить и оптимизировать, поскольку его структура и намерения автора очевидны.
Лучшая совместная работа: Когда код является самодокументируемым, команды разработчиков могут более эффективно сотрудничать, поскольку понимание кода не зависит от знаний одного человека или внешней документации.
Ускорение процесса ревью кода: Ревью кода становится более эффективным, когда код понятен и логичен, что способствует более быстрому и качественному обмену обратной связью.

Минусы

Сложность системы: Когда проекты становятся очень большими, сложность системы увеличивается экспоненциально. Самодокументируемый код, хоть и может быть понятным в малых масштабах, может не обеспечить достаточного уровня детализации и контекста для понимания сложных системных взаимодействий и архитектуры проекта в целом.
Множество разработчиков: В больших проектах обычно участвует много разработчиков с различным уровнем опыта и понимания кодовой базы. Сохранение кода "самодокументируемым" в таких условиях требует значительных усилий на согласование стандартов кодирования и обучение команды, что может быть не всегда возможно или эффективно.
Изменения и эволюция проекта: С течением времени проекты эволюционируют, и функциональные требования меняются. Без активного и постоянного рефакторинга код может быстро устареть и стать непонятным, даже если изначально был написан как "самодокументируемый". Это особенно верно для крупных проектов, где поддержание актуальности кода требует значительных ресурсов.
Необходимость в документации на высоком уровне: Самодокументируемый код может быть неэффективен для передачи архитектурных решений и общей структуры системы. В больших проектах часто требуется документация на высоком уровне, включая диаграммы архитектуры, описание интерфейсов и протоколов взаимодействия компонентов, которые не могут быть надлежащим образом выражены через код.
Кросс-функциональные команды: В больших проектах разработчики часто работают в кросс-функциональных командах вместе с аналитиками, тестировщиками, дизайнерами и другими специалистами, для которых понимание "самодокументируемого" кода может быть затруднительным без дополнительной документации.
Интеграция и зависимости: Большие проекты обычно включают множество внешних зависимостей, библиотек и сервисов. Понимание того, как эти компоненты интегрируются и взаимодействуют друг с другом, часто требует более подробной документации, чем может предоставить код сам по себе.

Тот самый мем, который вдохновил на статью

И как с этим быть?

Что делать? ~~Муравью шлем приделать~~ Мы видим, что минусы разрастаются и реализуются с ростом или масштабированием проекта, с появлением новых форков проекта, а также при увеличении команды. Когда пора в проекте озадачиться разработкой документации:

Если погружение нового разработчика занимает больше 2-3 недель:

В проектах, где для новых разработчиков сложно быстро начать эффективную работу, подробная документация может значительно ускорить процесс адаптации. Вы просто не будете впустую выкидывать деньги.

Если вы отдаете проект на эксплуатацию другой команде:

Уверяю Вас, что те кому вы передаете проект либо потратят 3-4 месяца на входе в проект, чтобы самим закатывать новые фичи, либо замучают вас звонками и вы проговорите всю ту же документацию словами. Уверен вы не кайфанете

Если проект переходит к заморозке:

Когда проект переводится в статус "заморожен" или завершается его активная разработка, подробная документация становится черным ящиком проекта. Как его реанимировать и быстро взять на эксплуатацию. Всегда закладывайте месяц, чтобы свернуть лавку =)

Обширное использование внешних зависимостей:

Постарайтесь выписать все внешние "кубики", которые вы используете для своего проекта. Если у вас их больше 10, то пишите доку. Кстати, если в проекте вы юзаете Keycloack, Kafka, RabbitMQ, Graphana, ClickHouse

Юридические и регулятивные требования:

Хотите поднять госденег, войти в реестр мегасупер Отечественног ПО, или просто получить сертификацию ФСТЭК - готовьте доку, очень много....

Ну или положитесь на чутье техдира (=

Я не один такой

Какую доку-то?

Так, ну есть ответ по джентльменскому набору, но это всегда разный перечень, я напишу то, что я планирую выпустить сам, или прошу сделать моего подрядчика:

Архитектурная документация: Описание высокоуровневой структуры системы, её компонентов и взаимосвязей между ними. Включает диаграммы архитектуры и описание ключевых решений. Те самые стрелки и квадратики

Руководства по стилю кодирования: Стандарты и конвенции кодирования, принятые в проекте, помогают поддерживать код консистентным и понятным для всех членов команды. Линтинг кода - наше все.

API и интерфейсная документация: Описание интерфейсов и API, предоставляемых системой, включая параметры, возвращаемые значения и примеры использования. Свагер - на стол.

Руководства пользователя и системные требования: Документация для пользователей и системных администраторов, описывающая, как использовать и настраивать систему, а также системные требования. Нужно описание как моя или ваша вундервафля работает. Даже в тачки кладут руководство по 1000 страниц. Хотя там все понятно.

Технические спецификации: Детальное описание функциональности, требований и ограничений системы, включая спецификации требований и дизайна. Это я прошу как заказчик, чтобы если меня спросят "Где деньги, Зин" мне было что показать. "Вот это сделано, и вот это... Смотрите как много сделано (="

Документация по развертыванию и настройке: Инструкции по развертыванию, настройке и обновлению системы, включая зависимости и конфигурационные файлы. Иначе мои девопсы меня придушат ночью.

Руководство по тестированию: Описание подходов к тестированию, включая юнит-тесты, интеграционные тесты и системные тесты, а также примеры тестовых случаев. В редких случаях, когда сценарии и корнер-кейсы не очевидны.

Часто задаваемые вопросы (FAQ) и решения проблем: Сборник ответов на часто задаваемые вопросы и типичные проблемы, с которыми сталкиваются пользователи и разработчики. Опционально.

Изменения и версионность: Журнал изменений (changelog), описывающий историю версий, включая добавленные функции, исправления ошибок и изменения в API. Это скорее для продактов, которые подхватят проект, чтобы была история. Разрабы глянут в гите.

По мере развития блога буду более детально углубляться в какие-то моменты. Надеюсь, что не навелосипедил, как обычно

Всех обнял,
The CTO