Документация имеет решающее значение для быстрого понимания класса и его методов. Исключения, как отмеченные, так и непроверенные, являются частью контракта метода и, следовательно, должны быть должным образом задокументированы, чтобы пользователи вашего кода могли быстро понять, как ведет себя ваш код.
Часть того, что делает хорошую документацию хорошей, заключается в том, что она очень специфична. Хотя документирование того, что метод выдает , не является ложью Исключение или даже Бросаемый это бесполезно. Мы должны стремиться генерировать (и, соответственно, документировать) наиболее конкретный тип исключения из возможных. Это особенно важно, когда мы документируем интерфейс, где документация интерфейса будет служить общей документацией для всех реализаций.
JavaDoc предлагает простой способ документирования исключений, создаваемых методом, с помощью throws тег. Эта первоклассная поддержка исключений в JavaDoc может использоваться как для проверенных, так и для непроверенных исключений. Особая вещь, которая может быть особенно полезна при документировании этих исключений, может превратиться в документацию предварительных условий для метода, которая может быть чрезвычайно полезна для пользователей вашего класса. Если из каждого метода в классе будет выдаваться конкретное исключение, вы можете выбрать использование комментария на уровне класса, который может в некоторой степени очистить документацию.
Документация чрезвычайно важна. Возможно, мы не всегда видим немедленную отдачу от этой документации, но по большому счету она может окупиться многократно.
Оригинал: “https://dev.to/kylec32/effective-java-document-all-exceptions-thrown-by-each-method-oad”