Зачем документировать код?
Документирование кода — очень полезная практика. Как минимум поможет в том, чтобы понять через какое-то время, что делает этот прекрасный метод, который вот прямо сейчас кажется таким понятным и логичным.
Через какое-то время сотрётся и понимание того, что он делает и логика его работы. При этом время может отличаться от пары дней до бесконечности, в зависимости от того, как часто и с какими частями проекта работаешь.
В последнее время я всё чаще склоняюсь к тому, что надо писать не только то, что делает тот или иной метод (ну или кусок кода), но и то, зачем это было введёно в проект.
Например часто методы наподобие StringUtils имеются в большинстве библиотек
И сами методы в них могут тоже пересекаться или чуть-чуть отличаться друг от друга (например, проверками или ещё чем-то)
Но иногда нужно писать предпосылки, потому что я сейчас у себя нашёл вот такой метод и ума не приложу, где он использовался.
Понятно, что можно найти в истории git’а использования, но с комменатарием, отвечающим на вопрос «ЗАЧЕМ???» было бы проще
А это точно нужно? Такой метод можно просто удалить, убедившись, что он уже не используется. В целом, как по мне, комментариев должен быть минимум и только там, где в коде происходит что-то контринтуитивное, а составлять, скажем, полные джавадоки на все методы — верный путь получить расхождение между реальной работой кода и устаревшими комментариями и, соответственно, путаницу. Самодокументируемый код, хоть он и не панацей, обычно лучше.
(конечно, есть особый случай — библиотеки, предназначенные для публичного доступа, но там и речь фактически не о комментариях, а о документации)
*панацея , понятно
Есть сложные методы, которые не всегда понятны. Есть методы которые были написаны для какого-то конкретного случая «на коленке». И не всегда к ним пишут документацию.
Если метод поменялся, то, конечно, надо обновлять javadoc, за этим надо следить на код ревью