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

Question

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

В разделе «Комментарии» на Java style guide, я нашел это:

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

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

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

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

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

/** 
* 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() 
*/ 

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

Answer 1

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

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

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

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

Answer 2

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

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

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

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

Answer 3

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

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

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