Заключительная глава этого раздела Эффективная Java подводит нас к любимой теме каждого – документации. Конкретный тип документации, которому посвящена эта глава, посвящен JavaDocs. Как уже обсуждалось ранее в этой серии, Эффективный Java , по-видимому, в основном ориентирован на авторов библиотек Java. Нигде этот фокус не проявляется так ярко, как в этой главе. Хотя я все еще думаю, что это может быть хорошей информацией для изучения вашим “средним” разработчиком Java, ее применимость может быть не такой высокой, как в других главах этой книги.
Поскольку применимость этой главы кажется мне более низкой, я думаю, что просто расскажу об основных моментах и предложу тем, кто заинтересован в том, чтобы узнать больше, углубиться в книгу, чтобы узнать подробности там.
- JavaDocs должны быть сосредоточены на контракте методов, на том, что должно быть задано, на предварительных условиях для этих переменных, на том, что будет возвращено, что происходит во время ошибок и побочных эффектов.
- Никакие два члена конструкторов в классе не должны использовать один и тот же JavaDoc
- JavaDoc часто визуализируется в HTML, это может быть использовано в ваших интересах, чтобы обеспечить лучшее форматирование, или может привести к ошибкам при случайном запуске этого синтаксического анализа, когда вы этого не ожидали.
- Тестирование JavaDoc часто сводится к тому, чтобы просто взглянуть на него и убедиться, что он выглядит правильно.
Существует много возможностей и возможностей для документирования вашего кода с помощью инструмента JavaDoc. Если вы возьмете на себя труд написать эту документацию, и вам следует это сделать, если основная цель вашего кода – быть использованным другими разработчиками Java, найдите время, чтобы сделать это правильно. Это означает сделать его полезным, полностью документировать, разместить JavaDoc где-нибудь в доступном месте и т.д. Наполовину выполненная работа с документацией, скорее всего, хуже, чем ее полное отсутствие. Также следует отметить, что, возможно, JavaDoc – не самый полезный тип документации для вашего конкретного кода, только вы узнаете об этом, когда посмотрите, как он будет использоваться.
Оригинал: “https://dev.to/kylec32/effective-java-write-doc-comments-for-all-exposed-apis-3nic”