Правильная ли практика добавления комментариев Javadoc в интерфейс и добавление комментариев не-Javadoc в реализацию?
Большинство IDE генерируют комментарии не-JavaDoc для реализаций при автоматическом создании комментариев. Не должен ли конкретный метод иметь описание?
Для методов, которые являются только реализацией (не переопределяет), конечно, почему бы и нет, особенно если они являются общедоступными.
Если у вас есть ситуация с превышением, и вы собираетесь копировать любой текст, то определенно нет. Репликация является верным способом возникновения расхождений. В результате у пользователей будет другое понимание вашего метода на основе того, изучают ли они метод в супертипе или подтипе. Используйте @inheritDoc или не предоставляйте документацию. В среде IDE будет использоваться самый низкий доступный текст для использования в представлении Javadoc.
В стороне, если ваша переопределяющая версия добавляет материал в документацию о супертипе, вы можете оказаться в мире проблем. Я изучил эту проблему во время своего PhD и обнаружил, что вообще люди никогда не будут знать о дополнительной информации в переопределенной версии, если они вызывают через супертип.
Решение этой проблемы было одной из основных особенностей созданного мною прототипа - всякий раз, когда вы вызывали метод, вы получили указание, что его цель или любые потенциальные переопределяющие цели содержали важную информацию (например, конфликтное поведение). Например, при вызове, помещенном на карту, вам напомнили, что если ваша реализация является TreeMap, ваши элементы должны быть сопоставимы.
И реализация, и интерфейс должны иметь javadoc. С помощью некоторых инструментов вы можете наследовать документацию интерфейса с помощью ключевого слова @inheritDoc.
/**
* @inheritDoc
*
* This implementation is very slow when b equals 3.
*/
public foo(int b)
{ ... }
В некоторой степени хорошая практика заключается в том, чтобы положить
/**
* {@inheritDoc}
*/
как реализация javadoc (если нет подробностей о деталях реализации).
@see Создает ссылку на описание в интерфейсе. Но я думаю, что также полезно добавить некоторые подробности об этой реализации.
Как правило, когда вы переопределяете метод, вы придерживаетесь контракта, определенного в базовом классе/интерфейсе, поэтому вы не хотите менять исходный javadoc. Поэтому использование тега @inheritDoc или @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 всегда показывают какую-либо ссылку по ссылке, которую вы можете щелкнуть, чтобы прочитать комментарий к базовому классу. Нет смысла смешивать их.
Sjoerd правильно говорит, что и интерфейс, и реализация должны иметь JavaDoc. Интерфейс JavaDoc должен определить контракт метода - то, что должен делать метод, какие данные он принимает, какие значения он должен вернуть и что он должен делать в случаях ошибки.
В документации по внедрению должны быть указаны расширения или ограничения по контракту, а также соответствующие детали реализации, особенно производительность.
Ради генерации javadoc да, это имеет значение. Если вы объявляете ссылки на конкретную реализацию, используя только интерфейс, это не происходит, поскольку средства интерфейса будут извлекаться с помощью среды IDE.