Написання документації для добре зрозумілих методів, таких як рівний на Java

Чи є хорошою практикою писати коментарі до широко відомих методів, таких як рівний, порівнянняДо тощо?

Розглянемо наведений нижче код.

 /**
 * This method compares the equality of the current object 
  with the object of same type
 */
@Override
public boolean equals(Object obj) {

               //code for equals

     }   

Моя компанія надає дані для коментарів, як описано вище. Чи потрібний вище коментар Javadoc? Хіба це не очевидно і добре зрозуміло, що робить метод рівних та лайків (порівняти, порівнювати) тощо?

Які ваші пропозиції?

JavaDoc вже підтримує успадкування коментарів . Згідно з документацією, "конструктори, поля та вкладені класи не успадковують коментарі doc", але такі методи, як equals()will. Оскільки в Objectкласі є добре задокументований equals()метод, ви можете просто мати можливість успадкувати цю документацію без проблем.

Документація методу повинна надходити звідкись, щоб вона була доступною у вашій IDE та в створеній веб-документації. Явно переписувати точні та вичерпні коментарі, які існують у суперкласі, не потрібно, і я заперечую, що захаращуються файли коду.

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

У моїй команді ми зазвичай використовуємо @inheritDocанотацію до equals()і , hashcode()але я бажаю , щоб ми не робили.

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

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

Пам'ятайте, що коментарі допомагають розробникам будь-якого роду, якщо вони правильні.

Проблема полягає в тому, що вони часом неповні і не точні.

Якщо чесно, порівняння двох об'єктів може бути складним (наприклад, порівняння двох об'єктів рахунків-фактур), також ваш метод може розвиватися з часом, і тоді його потрібно буде прокоментувати.

Показати мету методу, правила тощо у коментарі "корисного та змістовного" - це добре.

Вкрай погана практика засмічувати код вакуумними коментарями на кшталт:

/**
 * This method compares the equality of the current object with the object of same type...
 */

Це говорить нічого корисного. Гірше, вона бідна і в стилі, і в граматиці:

1. Коментарі ніколи не повинні починатися з "Цей метод" чи "Цей клас" чи "Цей". Коментар асоціюється з методом або класом за його місцезнаходженням у вихідному файлі.

2. "об'єкт" повинен читати "об'єкт"

3. "Порівняння рівності" має сенс лише в тому випадку, якщо один об'єкт може мати більше "рівності", ніж інший. Ця функція не порівнює "рівність"; вона порівнює об'єкти, щоб визначити їх рівність між собою.

Натомість коментар повинен вказувати, коли два об'єкти вважаються рівними. Тут я б повністю опустив опис методу і документував лише повернене значення, наприклад:

public class Fraction {
  private int numerator, denominator;
  /**
   * @return true if <i>this</i> is numerically equal to <i>other</i>
   */
  public boolean equals(Fraction other) {
    return numerator * other.denominator == other.numerator * denominator;
  }
...
}

Створені коментарі до тривіальних методів get / set - найгірші з усіх.

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

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

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

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

Крім того, я б сказав, що якщо код, який ви створюєте / редагуєте, не є загальнодоступним API, тоді просто залиште javadocs для загальних методів, оскільки вони просто додадуть безладу та шуму.