randall May 2 at 17:55

Встречают по README — что нужно знать о документации

Easy

6 min

9.1K

MWS corporate blogМТС corporate blogOpen source*Programming*Technical Writing*

Review

+23

Comments 4

gurovofficial May 2 at 21:20

Редми-файл ещё ладно, а вот некоторые в txt файлы всю архитектуру детально пишут и суют в репозиторий, вот это, на мой взгляд - перебор. У нас проект из-за этого нечитаемый стал. Вначале было забавно, но потом всё больше и больше документации в проект пихали. Если код нуждается в такой документации, значит с ним что-то не так. На мой взгляд такого не должно быть - код должен быть понятен.

Ksoo May 2 at 21:37

А что там в документации? Может там описание как должно работать, и при работе с кодом появляется возможность сравнить как должно.

ddruganov May 4 at 08:31

Для этого лучше подходят тесты

Ручками можно свихнуться сравнивать с тем, что в файлике

Ksoo May 5 at 01:43

Если эти тесты есть, а не пишется новый код
Если тесты покрывают интересующий сценарий
Если тесты правильно написаны

Зачастую ты идешь фиксить баг, когда тесты не нашли его.