Чи слід додавати коментарі Javadoc до реалізації?

109

Чи правильна практика додавати коментарі Javadoc в інтерфейс і додавати коментарі, що не є Javadoc, у реалізацію?

Більшість IDE генерують не-JavaDoc коментарі для реалізацій, коли ви автоматично генеруєте коментарі. Чи не повинен конкретний метод мати опис?

— Вайшак Суреш
джерело

67

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

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

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

Вирішення цієї проблеми було однією з найважливіших властивостей створеного мною інструменту прототипу - кожного разу, коли ви посилалися на метод, ви отримували вказівку, чи є його ціль або будь-які потенційні переважні цілі, які містять важливу інформацію (наприклад, конфліктну поведінку). Наприклад, коли ви посилаєте на карту, вам нагадували, що якщо ваша реалізація є TreeMap, ваші елементи повинні бути порівнянними.

— Урі
джерело

1

Ви вже не знаєте, що елементи повинні бути порівнянні при використанні TreeMap? Впровадження також не повинно реалізовувати конфліктну поведінку.

— Джиммі Т.

1

Я думаю , що це має бути правильною відповіддю stackoverflow.com/a/39981265/419516

— user219882

26

І реалізація, і інтерфейс повинні мати javadoc. За допомогою деяких інструментів ви можете успадкувати документацію інтерфейсу за допомогою ключового слова @inheritDoc.

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

— Веселий
джерело

5

Що таке "деякі інструменти"? Чи працює він у вікні чи пов'язаний з певними плагінами.

— jediz

Я знаю , використовує Eclipse , {@inheritDoc}і він працює тільки якщо ви НЕ маєте анотацію @Overrideперший

— ksnortum

24

Дещо хороша практика - це застосувати

/**
 * {@inheritDoc}
 */

як javadoc реалізації (якщо тільки щось додаткове не слід пояснити про деталі реалізації).

— Ваня
джерело

2

Сенс наявності інтерфейсу полягає в тому, що метод може бути реалізований декількома способами. Якщо я просто збираюся успадкувати коментарі, який сенс мати коментар у реалізації?

— Вайшак Суреш

16

Я використовую вищевказаний тег, а потім розміщую будь-яку додаткову необхідну документацію під тегом.

— Бен Пейдж

17

Як правило, коли ви переосмислюєте метод, ви дотримуєтесь договору, визначеного в базовому класі / інтерфейсі, тому ви не хочете жодним чином змінювати початковий 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.
 */

Чому? Тому що успадкований коментар, можливо, може бути дуже довгим. У такому випадку хто помітить зайве речення в кінці 3 довгих абзаців ?? Натомість просто запишіть частину власного коментаря, і це все. Усі інструменти javadoc завжди показують певну специфіку за посиланням, яке можна натиснути, щоб прочитати коментар базового класу. Немає сенсу їх перемішувати.

— Натікс
джерело

6

@see Це створює посилання на опис в інтерфейсі. Але я думаю, що добре також додати деякі деталі щодо реалізації.

— redben
джерело

6

ІМО, що використовує @seeпосилання на методи інтерфейсу, є хорошою практикою, і цього досить у більшості випадків. Коли ви копіюєте javadoc з інтерфейсного методу в конкретну реалізацію, ви просто дублюєте інформацію, і вона може швидко стати непослідовною. Однак будь-яка додаткова інформація про реалізацію повинна бути додана до javadoc.

— Пьотр

1

Додатковий документ полягає не в копіюванні документа з інтерфейсу, а просто в поясненні того, як ви реалізуєте метод і подібні речі. За допомогою документа інтерфейсу ви поясніть, які результати / цілі (стан програми чи повернення методу), тоді як у вашій реалізації може бути непогано пояснити, як ви досягаєте цих цілей.

— redben

4

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

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

— DJClayworth
джерело

0

Заради породженого javadoc так, це має значення. Якщо ви оголошуєте посилання на конкретну реалізацію, використовуючи лише інтерфейс, це не відбувається, оскільки методи інтерфейсу будуть знайдені IDE.

— Борис Павлович
джерело