Давай-давай, пиши документацию

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

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

Считаем, что в докстрингах должно быть описано назначение функций с пояснением каких-то особо хитрых моментов, описаны принимаемые и возвращаемые параметры. Мы используем гугл нотацию. Также в комплекте с докстрингами неразрывно идет аннотация типов. Это особенно важно, когда на входе какие-то сложные структуры данных. Целью является облегчение чтения кода.

Теперь о ридми. У нас на проектах ридми состоит из следующих блоков:
— Вводная часть, где тезисно указываем общее назначение сервиса. Если у сервиса чётко выраженное назначение, то описываем общий алгоритм работы.

— Установка и запуск. В этой части указываем набор команд, которые необходимо выполнить, чтобы запустить проект.
Подробность описания должна быть такая, чтобы при первом знакомстве с проектом разработчик скопировал из ридми команды и без матерных выражений запустил проект.

И, конечно, мы всё запускаем в докере. О важности докера у нас есть отдельный пост.

В этом же разделе также важно описать, как запускать тесты. Очень важно.

— Переменные окружения и опции. Сложный проект требует настройки, поэтому обязательно указываем набор переменных окружения, которые нужны в проекте, с описанием их назначения и дефолтными значениями.

— В разделе "другое" пишем о каких-то специфичных для проекта моментах. К таким особенностям может относится, например, накатывание миграций.

Последнее в нашем списке хорошо задокументированного проекта — тесты. Тесты являются самой актуальной документацией. В ридми можно забыть что-то поправить, а запуск тестов всегда показывает реальное поведение программы. Именно поэтому в ридми важно указывать, как запускать тесты.

Резюмируя, чем больше вы дадите информации о том, как запускать, как управлять проектом, какие у него есть особенности, тем лучше. Это облегчит вход любому разработчику. С увеличением числа проектов качественная документация становится критически важной. Во время разработки кажется: да всё понятно, как запускать эту штуку. А через пол года написанный вами проект будет выглядеть чужим и непонятным.

И ещё мысль по поводу документации:
Считаем вредным советом или требованием писать документацию в каких-то сторонних системах, таких как конфлюенс (да, порой и такое требуют). Практика показала, что поддержание документации в актуальном виде в стороннем сервисе, мягко говоря, не работает. Очень сложно убедить и даже заставить разработчика поддерживать доку где-то в сторонней приблуде. С ридми проще — можно писать, не отходя от кассы. И контролировать легче, проверяя изменение доки в merge request.
#devfm #procode