编写文档，了解Java中的equals等众所周知的方法

为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方法之类的方法（compare，compareTo）等不是很明显并且很好理解吗？

您有什么建议？

JavaDoc已经支持注释的继承。根据文档，“构造函数，字段和嵌套类不继承doc注释”，但可以使用诸如equals()will之类的方法。由于Object该类具有详细记录的equals()方法，因此您应该能够毫无问题地继承该文档。

该方法的文档需要来自某个地方，以便可以在您的IDE和生成的Web文档中进行访问。无需显式重写存在于超类中的准确而全面的注释，并且我认为代码文件混乱。

如果这是公司政策，那么您有两个选择。您可以轻松地使用它，并处理编写和维护文档的额外工作（通常违反DRY原理，该原理也可以应用于文档和代码）。另一种选择是寻求公司政策-解释为什么这个政策不是一个好主意，以及更改它的好处（从时间，金钱，精力，质量-管理层理解的方面）。

在我的团队中，我们通常将@inheritDoc标记用于equals()和，hashcode()但我希望我们不使用。

对于这两种方法，我始终必须查看实现。由于您要覆盖某个方法，这意味着您希望它做一些不同的事情。我认为这应该拥有自己的文档。

最好记录哪些属性参与该方法，甚至可能是为什么。

请记住，注释正确无误，可以帮助各种开发人员。

问题在于它们有时不完整且不准确。

老实说，比较2个对象可能比较棘手（例如，比较2个发票对象），而且您的方法可能会随着时间而发展，因此需要进行注释。

在“有用和有意义”的注释中显示方法的目标，规则等是一件好事。

用空虚的注释填充代码是极差的做法，例如：

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

这没什么用。更糟糕的是，它的样式和语法都很差：

1. 注释绝不能以“此方法”，“此类”或“ This”开头。注释通过其在源文件中的位置与方法或类相关联。

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方法生成的注释是最糟糕的。

我们的编码标准规定，在重写方法时，无需记录它，除非在重写方法时，父类或接口中的文档对于子类或实现类不再是准确而全面的。

对于equals，我们可能要注意，在比较数据库支持的实体时，仅对主键进行比较，因为这与的文档并不完全一致Object.equals()。

以我的观点，我认为这可能会引起争议，您应该在评论中指出您已改写了哪个班级。接下来六个月，当您想知道它是否已实现时，您无需打开课程就可以看到。

IMO知道这些方法是通用的，并且大多数开发人员都会知道它们的用途。您无需在此处添加任何注释。从长远来看，注释不是那么可靠，因为在更新实现时，注释可能不会被更新，并且可能引起混乱。因此，最好使代码可读，因为这是您最可信赖的。

此外，我想说的是，如果您创建/编辑的代码不是针对公共API的，则只需将javadocs留给常见方法，因为这些方法只会增加混乱和噪音。