Исправление Aber, (текущая версия) :
Я не знаю что у вас там творится, но поддержку заказчика. Дока на архитектуру и используемые алгоритмы нужна. Для этого обычно используют wiki где записываются все знания которые нужно передавать новым сотрудникам (не только по коду но и по инфраструктуре, и по настройки environment для работы). Там же на wiki помещаются ТЗ и хранится история изменений.
Я даже не знаю как без wiki работать над большим проектом. Вот допустим вам поступили требования на новую функциональность и тогда вы создаете wiki страницу с описанием того что нужно сделать, плюс все бизнес правила который должны быть реализованы в коде, если требования меняются вы там фиксируете изменения и согласования. Когда все будет реализовано наверное там стоит указать на ключевые места в написанном коде.
А вот в коде дока не нужна, конечно если это не дока над стабильным API, чего почти не бывает на живом проекте, разумеется это не касается передаваемых третьим лицам библиотек, фреймворков или публичных api. Если «контракт»(aka правила) не меняются, или даже правила выше по приоритету чем конкретная имплементация то тогда дока обязательно нужна в коде, где эти правила зафиксированы.
Исходная версия Aber, :
Я не знаю что у вас там творится, но поддержку заказчика. Дока на архитектуру и используемые алгоритмы нужна. Для этого обычно используют wiki где записываются все знания которые нужно передавать новым сотрудникам (не только по коду но и по инфраструктуре, и по настройки environment для работы). Там же на wiki помещаются ТЗ и хранится история изменений.
Я даже не знаю как без wiki работать над большим проектом. Вот допустим вам поступили требования на новую функциональность и тогда вы создаете wiki страницу с описанием того что нужно сделать, если требования меняются вы там фиксируете изменения и согласования. Когда все будет реализовано наверное там стоит указать на ключевые места в написанном коде.
А вот в коде дока не нужна, конечно если это не дока над стабильным API, чего почти не бывает на живом проекте, разумеется это не касается передаваемых третьим лицам библиотек, фреймворков или публичных api. Если «контракт»(aka правила) не меняются, или даже правила выше по приоритету чем конкретная имплементация то тогда дока обязательно нужна в коде, где эти правила зафиксированы.