Следует ли добавлять в реализацию комментарии Javadoc?

109

Правильно ли добавлять комментарии Javadoc в интерфейс и добавлять комментарии не Javadoc в реализацию?

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

Вайшак Суреш
источник

Ответы:

67

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

Если у вас сложная ситуация и вы собираетесь воспроизвести любой текст, то определенно нет. Репликация - верный способ вызвать расхождения. В результате пользователи будут по-разному понимать ваш метод в зависимости от того, исследуют ли они метод в супертипе или в подтипе. Использовать @inheritDocили не предоставлять документацию - среды IDE будут использовать наименьший доступный текст для использования в представлении Javadoc.

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

Решение этой проблемы было одной из основных функций созданного мною прототипа инструмента - всякий раз, когда вы вызывали метод, вы получали указание, содержит ли его цель или любые потенциальные замещающие цели важную информацию (например, конфликтующее поведение). Например, при вызове команды «Положить на карту» вам напомнили, что если ваша реализация представляет собой TreeMap, ваши элементы должны быть сопоставимы.

Ури
источник
1
Разве вы еще не знаете, что элементы должны быть сопоставимы при использовании TreeMap? Реализация также не должна реализовывать конфликтное поведение.
Джимми Т.
1
Думаю, это должен быть правильный ответ stackoverflow.com/a/39981265/419516
user219882
26

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

/**
 * @inheritDoc
 *
 * This implementation is very slow when b equals 3.
 */
public foo(int b)
{ ... }
Sjoerd
источник
5
Что такое «некоторые инструменты»? Работает ли он из коробки или привязан к каким-то конкретным плагинам.
jediz
Я знаю , использует Eclipse , {@inheritDoc}и он работает только если вы не имеете аннотацию @Overrideпервый
ksnortum
24

В некоторой степени хорошая практика - поставить

/**
 * {@inheritDoc}
 */

как javadoc реализации (если нет дополнительных пояснений по поводу деталей реализации).

Ваня
источник
2
Смысл интерфейса в том, что метод может быть реализован несколькими способами. Если я просто унаследую комментарии, какой смысл иметь комментарий в реализации?
Вайшак Суреш
16
Я использую указанный выше тег, а затем помещаю всю необходимую дополнительную документацию под тегом.
Бен Пейдж
17

Обычно, когда вы переопределяете метод, вы придерживаетесь контракта, определенного в базовом классе / интерфейсе, поэтому вы все равно не хотите изменять исходный javadoc. Поэтому использование тега @inheritDocor, @seeупомянутого в других ответах, не требуется и фактически служит только шумом в коде. Все разумные инструменты наследуют метод javadoc от суперкласса или интерфейса, как указано здесь :

Inherit from classes and interfaces - Inheriting of comments occurs in all
three possible cases of inheritance from classes and interfaces:

- When a method in a class overrides a method in a superclass
- When a method in an interface overrides a method in a superinterface
- When a method in a class implements a method in an interface

Тот факт, что некоторые инструменты (я смотрю на вас, Eclipse!) Генерируют их по умолчанию при переопределении метода, является лишь печальным положением вещей, но не оправдывает загромождения вашего кода бесполезным шумом.


Конечно, может быть и обратный случай, когда вы действительно хотите добавить комментарий к методу переопределения (обычно некоторые дополнительные детали реализации или немного более строгий контракт). Но в этом случае вам почти никогда не захочется делать что-то вроде этого:

/**
 * {@inheritDoc}
 *
 * This implementation is very, very slow when b equals 3.
 */

Зачем? Потому что унаследованный комментарий может быть очень длинным. В таком случае, кто заметит лишнее предложение в конце трех длинных абзацев ?? Вместо этого просто запишите отрывок из собственного комментария и все. Все инструменты javadoc всегда показывают какую-либо ссылку, указанную пользователем, по которой вы можете щелкнуть, чтобы прочитать комментарий базового класса. Смешивать их нет смысла.

Натикс
источник
6

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

Redben
источник
6
Использование IMO @seeссылок на методы интерфейса является хорошей практикой, и в большинстве случаев этого достаточно. Когда вы копируете javadoc из метода интерфейса в конкретную реализацию, вы просто дублируете информацию, и она может быстро стать несовместимой. Однако любая дополнительная информация о реализации должна быть добавлена ​​в javadoc.
Петр
1
Дополнительный документ предназначен не для копирования документа из интерфейса, а просто для объяснения того, как вы реализуете метод и тому подобное. С помощью документа по интерфейсу вы объясняете, какие результаты / цели (состояние приложения или метод возвращаются), тогда как в вашей реализации может быть полезно объяснить, как вы достигаете этих целей.
redben
4

Шёрд правильно говорит, что и интерфейс, и реализация должны иметь JavaDoc. Интерфейс JavaDoc должен определять контракт метода - что должен делать метод, какие входные данные он принимает, какие значения он должен возвращать и что он должен делать в случае ошибки.

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

DJClayworth
источник
0

Ради сгенерированного javadoc да, это имеет значение. Если вы объявляете ссылки на конкретную реализацию, используя только интерфейс, то этого не произойдет, поскольку методы интерфейса будут извлечены IDE.

Борис Павлович
источник