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

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

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

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

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

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