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

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

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

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

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

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

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

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

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

Добавить комментарий

Заполните поля или щелкните по значку, чтобы оставить свой комментарий:

Логотип WordPress.com

Для комментария используется ваша учётная запись WordPress.com. Выход / Изменить )

Фотография Twitter

Для комментария используется ваша учётная запись Twitter. Выход / Изменить )

Фотография Facebook

Для комментария используется ваша учётная запись Facebook. Выход / Изменить )

Google+ photo

Для комментария используется ваша учётная запись Google+. Выход / Изменить )

Connecting to %s