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