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

Документация на ПО содержится в коде.

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

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

Код дает окончательный ответ.

Если документация содержится в коде, значит и требования к коду предъявляются особые:

1. Код должен быть удобочитаемым, чтобы читатель кода мог быстро понять, что делает код и получить ответ на вопрос по поведению системы.
2. Код должен быть кратким
3. Код должен придерживаться единого стиля, принятого в программе, и единых подходов

Хорошие книги по этой теме:

1. Clean code  Роберта Мартина. В русском переводе она продается под названием «Чистый код»
2. Art of readable code