Вы написали сложный алгоритм, всё работает, тесты проходят. Рука тянется нажать «Коммит» и забыть. Зачем тратить время на комментарии, если вы и так помните, что сделали? Но попробуйте вернуться к этому коду через полгода, после ночи без сна или в состоянии стресса. Вы смотрите на знакомые строки и думаете: «Кто писал этот бред? А, это я…». Память — ненадёжный инструмент. Она стирает детали, искажает контекст, подменяет причины следствия. Как если бы вы через полгода пытались вспомнить, зачем положили ключ именно в этот ящик, а не в тот. Документация — это записка для себя будущего и для коллеги, который будет поддерживать проект. Без неё код превращается в древний свиток на забытом языке: вроде буквы знакомые, а смысл ускользает...
Подробнее в ВКонтакте

@whilet_ru