Комментарии к переопределенному методу в Java

Question

Должны ли мы комментировать переопределенный метод или нет? Если да, то будет ли комментарий документом Java или простым комментарием?

Answer 1

@ Ответ SimonC объясняет, как утилита javadoc генерирует «унаследованную» документацию для переопределенных методов.

Вы также можете поместить явные javadoc в метод переопределения, и они будут иметь приоритет над унаследованными javadocs. Кроме того, если вы поместите тег {@inheritDoc} в явный javadocs метода переопределения, унаследованные комментарии будут включены в этот момент.

Чтобы ответить на это:

Должны ли мы комментировать переопределенный метод или нет? Если да, то будет ли комментарий документом Java или простым комментарием?

По моему мнению, если метод переопределения уточняет документированную семантику (контракт) переопределенного метода (или ... небеса запрещают ... нарушает контракт), то это заслуживает документирования в javadocs метода переопределения. Однако, если различия являются просто «деталями реализации», тогда более подходящими являются простые комментарии (или отсутствие комментариев).

(Тем не менее, практика включения «не-Javadoc» комментария, который отсылает читателя обратно к Javadoc переопределенного метода, это, IMO, пустая трата экранной недвижимости ... когда я читаю исходный код.)

Answer 2

С Как писать комментарии к документу для инструмента Javadoc :

Автоматическое повторное использование комментариев метода

Вы можете избежать повторного ввода комментариев к документузная, как инструмент Javadoc дублирует (наследует) комментарии для методов, которые переопределяют или реализуют другие методы.Это происходит в трех случаях: когда метод в классе переопределяет метод в суперклассе, когда метод в интерфейсе переопределяет метод в суперинтерфейсе, когда метод в классе реализует метод в интерфейсе. В первых двух случаях, еслиmethod m () переопределяет другой метод, инструмент Javadoc сгенерирует подзаголовок «Overrides» в документации для m () со ссылкой на метод, который он переопределяет.

В третьем случае, если методm () в данном классе реализует метод в интерфейсе, инструмент Javadoc сгенерирует подзаголовок «Определено» в документации для m () со ссылкой на метод, который он реализует.

ВВо всех этих трех случаях, если метод m () не содержит комментариев или тегов документа, инструмент Javadoc также скопирует текст метода, который он переопределяет или реализует, в сгенерированную документацию для m ().Поэтому, если документации переопределенного или реализованного метода достаточно, вам не нужно добавлять документацию для m ().Если вы добавите какой-либо комментарий к документации или тег в m (), подзаголовок и ссылка «Переопределение» или «Указано» все равно будут отображаться, но текст не будет скопирован.