Java doc - неотъемлемая часть нашего кода. Код всегда пишется исходя из задачи. Но есть такое понятие, как intention (намерение) разработчика, и зачастую не понятно, почему код написан именно так, и никак иначе. Возникает вопрос: "что имел ввиду тот, кто писал этот код"? Может он знал что-то, чего не знаю я? А может наоборот, и это просто ошибка или упущение разработика? Почему он сделал проверку здесь? Почему входной параметр не может быть отрицательным и т.д.?
Intention это часть проблемы. Другая ее часть заключается в понимании того, как работать с кодом, который написан другим разработчиком. Какой пререквизит нужен, чтобы его код работал корректно? Является ли он потокобезопасным? Какие входные параметры являются валидными, а какие нет? Что будет, если отправить в метод невалидный параметр? Может ли метод вернуть null и нужно ли мне делать на это проверку? На все эти вопросы отвечает контракт. Контракт - это описанное вашего функционала - описание пакета, класса, метода. Описание всех граничных случаев (corner cases). Контракт - это документация к вашей "кофемашине". Прежде чем пользоваться чем либо мы читаем документацию, чтобы понять, как это делать правильно, и что требуется для этого. Так же и с кодом - мы не должны вскрывать его и разбираться в тонкостях реализации (вы же не разбираете кофемашину, чтобы понять, как ее чистить от накипи). Качественно написанный код не требует этого. Он должен быть хорошо задокументирован и описывать все возможное случаи использования. Если вы не можете их описать - скорее всего, потому что вы сами толком не знаете, как работает ваш код. Если вы пишете качественный код - вы знаете для чего он написан. В каких случаях он работает, а в каких нет. Вы можете дать гарантию на его работоспособность при различных обстоятельствах.
Качественной документацией вы экономите тонну времени другим разработчикам, которые в будущем будут работать с вашим кодом. Когда на проде всплывает критичный баг, нет времени на то, чтобы сидеть и разбираться в том, как написан ваш код, делать сотни догадок о ваших намерениях и строить гипотезы на различные корнер кейсы, в которых ваш код будет работать или нет. Проблему нужно решать здесь и сейчас. Чем быстрее мы это сделаем, тем лучше для всех. Копание и корпение над чужим кодом не дает никакого инкремента, никакого value (если только вы не делаете этого в ваше личное время для саморазвития).
P.S. Не ограничивайте себя только документацией. Используйте всю мощь статического анализатора, а так же общепринятых конвенций. Пользуйтесь наработками JSR-305. Читайте и разбирайтесь в том, как работает код в крупных opensource проектах. Какие решения они используют там.
Intention это часть проблемы. Другая ее часть заключается в понимании того, как работать с кодом, который написан другим разработчиком. Какой пререквизит нужен, чтобы его код работал корректно? Является ли он потокобезопасным? Какие входные параметры являются валидными, а какие нет? Что будет, если отправить в метод невалидный параметр? Может ли метод вернуть null и нужно ли мне делать на это проверку? На все эти вопросы отвечает контракт. Контракт - это описанное вашего функционала - описание пакета, класса, метода. Описание всех граничных случаев (corner cases). Контракт - это документация к вашей "кофемашине". Прежде чем пользоваться чем либо мы читаем документацию, чтобы понять, как это делать правильно, и что требуется для этого. Так же и с кодом - мы не должны вскрывать его и разбираться в тонкостях реализации (вы же не разбираете кофемашину, чтобы понять, как ее чистить от накипи). Качественно написанный код не требует этого. Он должен быть хорошо задокументирован и описывать все возможное случаи использования. Если вы не можете их описать - скорее всего, потому что вы сами толком не знаете, как работает ваш код. Если вы пишете качественный код - вы знаете для чего он написан. В каких случаях он работает, а в каких нет. Вы можете дать гарантию на его работоспособность при различных обстоятельствах.
Качественной документацией вы экономите тонну времени другим разработчикам, которые в будущем будут работать с вашим кодом. Когда на проде всплывает критичный баг, нет времени на то, чтобы сидеть и разбираться в том, как написан ваш код, делать сотни догадок о ваших намерениях и строить гипотезы на различные корнер кейсы, в которых ваш код будет работать или нет. Проблему нужно решать здесь и сейчас. Чем быстрее мы это сделаем, тем лучше для всех. Копание и корпение над чужим кодом не дает никакого инкремента, никакого value (если только вы не делаете этого в ваше личное время для саморазвития).
P.S. Не ограничивайте себя только документацией. Используйте всю мощь статического анализатора, а так же общепринятых конвенций. Пользуйтесь наработками JSR-305. Читайте и разбирайтесь в том, как работает код в крупных opensource проектах. Какие решения они используют там.