Документация
Ох сколько проблем вызывает документация. И зачастую эти проблемы связаны с ее отсутствием. Почти всегда разработчики считаю что написание документации это: лишнее, бюрократия, скучно. Также часто разработчики приводят в пример цитату из скрам гайда: работающий продукт важнее исчерпывающей
документации.
Я считаю что документация в том или ином виде должна присутствовать. Зачастую ее ценность понимается не сразу, а по прошествию времени. Например так случилось и в нашей команде, когда старые разработчики ушли и новеньким было очень сложно делать экскурс по системе, а она очень большая!
Но я против детально и огромной документации. Для себя и своих личных проектов я придерживаюсь следующего шаблона. Он достаточно компактный и простой в написании. Да это не ГОСТ, не ISO и не IEEE. Но она понятная и ее написание не занимает много времени.
Какие проблемы я пробую решить своим шаблоном:
- Для чего нужен данный модуль или архитектура?
- Как ее использовать?
- Как вносить изменения?
- Как осуществлять диагностику или проверку состояния?
- Какие были связаны с ней проблемы?
- Какими тестами покрыто? (Проблема очень важная, так как часто при планировании изменений приходилось вспоминать/идти проверять какими тестами покрыт функционал, что отнимало иногда много времени).
Шаблон документации
Назначение: для чего нужен этот модуль, какую задачу решает?
Основная задача: ссылка на задачу в трекере в рамках которой разрабатывалась данный модуль.
Диаграмма: графическое отображение архитектуры. Позволит понять что от кого зависит и как взаимодействует с другими частями системы.
Зоны ответственности: кратко описать элементы модуля и за что они отвечают. Смысл приёма в том, чтобы явно выделить назначение класса. Идеальный результат — получить класс, который можно описать одной фразой или даже одним словом.
Пример использования: небольшой пример того как использовать данный функционал.
Обработка ошибок: как обрабатываются ошибки.
Логирование:
- В какой файл пишутся логи.
- Уровни логирования и какую они могут дать информацию.
Тесты: каким типом тестов покрыта данная функциональность.
FAQ: вопросы и ответы по данной функциональности. Например: как объединить 2 объекта в сущности?
Инциденты и баги: ссылки на баги, которые были найдены в данной функциональности и исправленные.