Зачем эти хлопоты? Ведь ваша команда знает, как все устроено, – это знание передается из поколения в поколение. Кроме того, ваш технологический стек так грамотно спроектирован и внедрен, что в нем разберется любой толковый специалист. Если вы так думаете, то, вероятно, еще и уверены, что ваш код не содержит ошибок и, следовательно, не требует тестирования! Звучит абсурдно, но многие действительно так считают.

Документация – это преемственность. Документация – это масштабируемость. Документация – это свобода. Это не признак слабости и не формалистская рутина, которую приходится терпеть и которую можно откладывать на самый последний момент.

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

Люди забывают детали. По мере того как дни складываются в недели, недели – в месяцы, а месяцы – в годы, забывается причина, по которой что-то было сделано именно так, а не иначе. Нестандартное бизнес-правило или неочевидное ограничение, которое в свое время направило архитектуру/реализацию в ту или иную сторону (и в то время это решение было верным), в будущем может оказаться не столь понятным. С решениями, причины которых затерялись в прошлом, произойдет одно из двух:

• Новый сотрудник увидит его, подумает, что можно сделать все проще, переделает – и в итоге что-то сломается.

• Люди будут бояться трогать решение или тем более пытаться его переделать. Оно приобретет мифические свойства и будет считаться слишком сложным или важным, чтобы рисковать и вносить в него изменения.

Оба сценария несут большую опасность, и обоих можно полностью избежать, если оставить краткие пояснения. Как однажды заметил один мудрый разработчик: «Комментарии [в коде] – это любовные записки будущему самому себе».