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

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

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

7 87
javascript interface javadoc comments

7 ответов:

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

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

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

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

55

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

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

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

/**
 * {@inheritDoc}
 */

как javadoc реализации (если нет чего-то дополнительного, чтобы быть объясненным о деталях реализации).

20

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

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

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

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

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

10

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

6

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

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

4

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

0