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

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

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

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

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

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

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

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

/**
 * @inheritDoc
 *
 * This implementation is very slow when b equals 3.
 */
public foo(int b)
{ ... }

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

/**
 * {@inheritDoc}
 */

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

Обычно, когда вы переопределяете метод, вы придерживаетесь контракта, определенного в базовом классе / интерфейсе, поэтому вы все равно не хотите изменять исходный 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 всегда показывают какую-либо ссылку, указанную пользователем, по которой вы можете щелкнуть, чтобы прочитать комментарий базового класса. Смешивать их нет смысла.

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

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

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

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