Написание документации для хорошо понятных методов, таких как equals в Java

Является ли хорошей практикой писать комментарии для широко известных методов, таких как equals, compareTo и т. Д.?

Рассмотрим приведенный ниже код.

 /**
 * 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? Разве это не очевидно и хорошо понятно, что делает метод equals, лайки (сравнивают, сравнивают) и т. Д.?

Каковы ваши предложения?

JavaDoc уже поддерживает наследование комментариев . Согласно документации, «конструкторы, поля и вложенные классы наследуют не комментарии документа», а такие методы, как equals()воля. Поскольку у Objectкласса есть хорошо документированный equals()метод, вы должны просто унаследовать эту документацию без проблем.

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

Если это корпоративная политика, то у вас есть два варианта. Вы можете быстро согласиться с этим и справиться с дополнительными усилиями по написанию и ведению документации (часто в нарушение принципа СУХОЙ, который также может применяться к документам и коду). Другой вариант заключается в том, чтобы искать политику компании - объяснить, почему эта политика не является хорошей идеей, а также преимущества ее изменения (с точки зрения времени, денег, усилий, качества - вещей, которые понимает руководство).

В моей команде мы обычно используем @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 для распространенных методов, поскольку они просто добавят беспорядок и шум.