Javadoc комментарии против блочных комментариев?

Question

Когда уместно использовать блочный комментарий в начале методов, и когда уместно использовать комментарий в стиле javadoc?

Из раздела «Комментарии» Руководства по стилю Java я нашел это:

Java-программы могут иметь два вида комментарии: комментарии реализации и комментарии к документации. Реализация комментарии найдены в C ++, который ограничены /*...*/ и //. Комментарии к документации (известные как "doc" комментарии ") только для Java и ограничены /**...*/. Док комментарии может быть извлечен в файлы HTML с помощью инструмент Javadoc.

Комментарии к реализации предназначены для комментируя код или для комментариев о конкретной реализации. Комментарии к документу предназначены для описания спецификация кода, от перспектива без реализации. быть прочитано разработчиками, которые могут не обязательно иметь исходный код на рука.

Итак, еще один способ сформулировать мой вопрос: когда методы заслуживают спецификации кода с точки зрения реализации (Javadoc) вместо комментария о конкретной реализации, и наоборот? Будет ли интерфейс получать комментарии Javadoc, а реализации - комментарии блока?

edit: Я думаю, что не правильно формулирую свой вопрос, основываясь на полученных до сих пор ответах.

Вот пример того, что я хочу знать.

/**
 * Javadoc comment here about general implementation?
 */
/*
 * Should I now have a separate block comment for my specific implementation?
 */
public void foo()
{
...
}

Два разных стиля комментариев передают два разных типа информации. Существуют ли случаи, когда методы должны иметь ОБА передний комментарий javadoc и передний комментарий блока?

Вдохновение даже спрашивать - Eclipse автоматически сгенерировал это для меня прямо сейчас:

/*
 * (non-Javadoc)
 * @see my.package#process()
 */

И я подумал, что здесь происходит какая-то стилизация, которая не указана конкретно в спецификациях комментариев, на которые я ссылаюсь выше.

Answer 1

Информация, которую должен знать пользователь класса , должна быть в комментарии Javadoc.

Информация о том, что разработчик, модифицирующий класс , должен знать, входит в обычный комментарий (блок или строку).

И вполне возможно, что любой блок кода (класс, интерфейс, поле, метод, конструктор, ...) может иметь оба комментарий Javadoc и обычный блок комментария, когда оба публично видны как также требуется внутренний документ.

Лично я склонен писать очень мало не-Javadoc комментариев, потому что я предпочитаю структурировать свой код так, чтобы он самодокументировался.

Answer 2

По моему мнению, комментарии Javadoc - это комментарии, которые вы пишете людям, которые используют ваш код и которые вызывают ваши методы.

Комментарии Javadoc более сфокусированы на параметрах методов, которые ваш метод будет возвращать в зависимости от параметров, которые вы даете своим методам.

Блочные комментарии - это внутренние комментарии, комментарии, которые вы пишете для людей, поддерживающих ваш код.

Блочные комментарии важны для понимания того, как работает код, почему он работает и какие операции используются для выполнения реальной работы.

Answer 3

По моему мнению, нет смысла размещать блочные комментарии в начале метода (ну, никогда не говори никогда, но, по крайней мере, большую часть времени). Комментарии Javadoc относительно методов интерфейса определяют контракт, о методах класса, которые они рассказывают о реализации, чтобы пользователь мог решить, какой класс использовать, если существует несколько классов, реализующих один интерфейс. Подумайте об интерфейсе List; реализации ArrayList и LinkedList подходят для разных случаев использования, поэтому их соответствующие документы могут объяснить их плюсы и минусы.

Я в блоке комментирую очень специфические вещи. Я хочу, чтобы конкретный документ по реализации был непосредственно там, где есть реализация. Конечно, вы должны использовать их как можно реже. Используйте выразительные имена переменных и методов, и они автоматически добавляют низкоуровневую документацию.

Автоматически сгенерированные блочные комментарии Eclipse для вас, чтобы заполнить и, возможно, сделать их комментариями Javadoc, добавив пропущенную звездочку. Я не знаю точно, в каких случаях они появляются, но один - когда вы извлекаете интерфейс из существующего класса. Затем Javadoc из класса переходит к методу интерфейса, а метод класса получает комментарий блока. Причиной этого является то, что часто при реализации интерфейса вам не так много нужно добавить. Я снова использую List в качестве примера. Методу size() больше не потребуется документация в реализациях ArrayList и LinkedList. Им нечего добавить. Конечно, этот пример является надуманным, потому что фактические реализации (по крайней мере, OpenJDK) do имеют Javadocs, но я не вижу в этом необходимости и, действительно, ничего не добавляющего. Хуже того, они предоставляют даже меньше информации, чем документация интерфейса.