Комментарии Javadoc против комментариев блока?

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

В разделе "Комментарии" в руководстве по стилю Java я нашел следующее:

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

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

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

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

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

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

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

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

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

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

Ответ 1

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

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

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

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

Ответ 2

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

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

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

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

Ответ 3

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

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

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