Документация

Документация для кода и логики системы

Документирование программного кода

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

Документирование логики работы системы

Развиваясь информационные системы могут обрастать большим количеством функций, логику работы которых не сможет вспомнить даже ее разработчик (не говоря о командах, аналитиках и заказчиках). Целесообразно разрабатывать и поддерживать документацию по внутренней логике системы, вмонтировать поддержку ее актуальности части процесса и хранить документацию в репозитории вместе с кодом проекта.

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