Comments 1
Я пишу апи и создаю документацию для бэкендеров и других в команде заставляю. Потому что коду не хватает выразительности и люди долго реверсят из него, что хотел сказать автор. А потом не понимают замысла и делают всё поперёк. В итоге, знания хранятся в людях.
В этой доке находятся заложенные идеи, чтобы тот кто хочет погрузиться в проект или в какую-то незнакомую часть мог быстро разобраться что к чему, не реверсируя это из кода.
Я кучу раз сталкивался со странным кодом и не было никакой подсказки - это так задумано, или автор ошибся? Да, тестов тоже не было, как не трудно догадаться. И тут ещё один источник истины с намерениями помог бы.
А если нужно написать какой-то сложный процесс, то коду не хватает выразительности и хорошо бы иметь общую схему, которая будет гораздо короче и содержать всё в одном месте.
Да, код работает в соответствии с кодом, а не документацией и есть проблема с тем, что дока и код разъезжаются. Я решаю эту проблему с помощь дисциплины и ревью. Дока хранится в репе, и если в коде поменялось что-то значимое, а дока не поменялась, значит нужно поменять или дописать.
Сейчас возлагаю надежды на LLM, чтобы они сравнивали написанное в доке с написанным в коде. Или отвечала на вопросы вида: я хочу сделать ххх, что мне нужно знать?
Documentation-Driven Development