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

10

Является ли хорошей практикой писать комментарии для широко известных методов, таких как 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, лайки (сравнивают, сравнивают) и т. Д.?

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

Винот Кумар СМ
источник
3
Ваш текущий комментарий неверен. Подпись вашего метода верна при использовании универсального объекта Object, но ваш комментарий говорит «объект того же типа».
c_maker
4
Я предпочел бы увидеть комментарий, объясняющий, что означает равенство для этого объекта. «Равенство» - это скользкий термин. В Common Lisp существует множество функций равенства, и вы выбираете подходящую для использования.
Дэвид Торнли
В данном случае я имею в виду два значимых объекта, равных. Например, два объекта Employee равны, если они имеют одинаковый идентификатор сотрудника, а не говорят, что они носят рубашку одного цвета.
Винот Кумар CM
6
@Vinoth: «осмысленный путь» - это именно то, что вам нужно документировать :)
c_maker

Ответы:

6

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

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

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

Томас Оуэнс
источник
Я знаю о наследовании. Но компания «обязывает» нас писать явные документы на Java.
Винот Кумар CM
3
@Vinoth Если это политика компании, то вы ничего не можете сделать, кроме как написать ее или попытаться изменить политику. Если вы используете современные инструменты разработки, то эта политика устарела. Что движет этой политикой? Комментарии JavaDoc превращаются в веб-страницы, а современные IDE позволяют просматривать комментарии JavaDoc при написании программного обеспечения независимо от того, откуда поступил комментарий (явный или унаследованный).
Томас Оуэнс
@ Томас: Существует вариант прощения, а не просьбы разрешения: просто молча согните правила и посмотрите, если кто-нибудь пожалуется.
dsimcha
@dsimcha Возможно, но если это повторить, это может быть плохо для работы. Это не одно или два раза.
Томас Оуэнс
9

В моей команде мы обычно используем @inheritDocаннотацию к equals()и , hashcode()но я желаю , чтобы мы не делали.

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

Хорошо, по крайней мере, документировать, какие атрибуты участвуют в методе, и даже, возможно, почему это так.

c_maker
источник
1
Ваше последнее утверждение - лучшая причина для его документирования. Объясните, что он делает. Конечно, equal () может сравнивать каждый элемент в классе, или вы можете просто сравнить все строковые поля или что-то еще.
Николас
2

Помните, что комментарии помогают разработчикам всех видов, если они верны.

Проблема в том, что они иногда неполны и не точны.

Чтобы быть честным, сравнение двух объектов может быть сложным (например, сравнение двух объектов счета-фактуры), также ваш метод может развиваться со временем, и тогда его необходимо будет прокомментировать.

Хорошая вещь - показать цель метода, правила и т. Д. В «полезном и содержательном» комментарии.

Без шансов
источник
2

Чрезвычайно плохая практика засорять код пустыми комментариями, такими как:

/**
 * 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 являются худшими из всех.

Кевин Клайн
источник
1

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

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

Kris
источник
0

На мой взгляд, и я думаю, что это может быть спорным, вы должны указать в комментарии, в каком классе вы переопределены класс. Затем через шесть месяцев, когда вам станет интересно, реализовано ли это или нет, вы сможете увидеть, не открывая урок.

Питер Тейлор
источник
0

Зная, что эти методы распространены, и большинство разработчиков будут знать, для чего они нужны, IMO, вам не нужно будет оставлять там комментарии. Комментарии не настолько надежны в долгосрочной перспективе, поскольку есть вероятность, что они могут не обновляться при обновлении реализации и могут привести к путанице. Поэтому всегда лучше сделать код читабельным, так как это то, чему вы в основном можете доверять.

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

Боб Сантос
источник