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 메소드와 좋아요 (comare, compareTo) 등이 무엇을하는지는 명확하지 않으며 잘 이해되지 않습니까?

당신의 제안은 무엇입니까?

JavaDoc은 이미 주석 상속을 지원합니다 . 문서에 따르면, "생성자, 필드 및 중첩 클래스는 문서 주석을 상속하지 않습니다"와 같은 방법 equals()입니다. 때문에 Object클래스는 잘 문서화이 equals()방법을, 당신은 문제없이이 문서를 상속 할 수 있어야한다.

메소드의 문서는 IDE 및 생성 된 웹 문서에서 액세스 할 수 있도록 어딘가에서 가져와야합니다. 수퍼 클래스에 존재하는 정확하고 포괄적 인 주석을 명시 적으로 다시 작성하는 것은 필요하지 않으며 코드 파일이 복잡해집니다.

이것이 회사 정책 인 경우 두 가지 옵션이 있습니다. 문서를 작성하고 유지 관리하기위한 추가 노력 (종종 문서와 코드에도 적용 할 수있는 DRY 원칙을 위반 함)을 처리 할 수 ​​있습니다. 다른 옵션은 회사 정책을 찾는 것입니다.이 정책이 왜 좋은 아이디어가 아니며 정책 변경의 이점 (시간, 비용, 노력, 품질-경영진이 이해하는 측면에서)을 설명하십시오.

우리 팀에서 우리는 일반적으로 사용 @inheritDoc에 대한 주석 equals()및 hashcode()하지만 우리가하지 않았다 바랍니다.

이 두 가지 방법의 경우 항상 구현을 살펴 봐야합니다. 메서드를 재정의하기 때문에 다른 방법을 원합니다. 나는 이것이 자체 문서를 가질 가치가 있다고 생각합니다.

최소한 어떤 속성이 메소드에 참여하는지, 그리고 왜 그런지 문서화하는 것이 좋습니다.

의견은 모든 종류의 개발자가 올바른 경우 도움이됩니다.

문제는 때로는 불완전하고 정확하지 않다는 것입니다.

솔직히 말해서 2 개의 객체를 비교하는 것은 까다로울 수 있습니다 (예 : 2 개의 송장 객체 비교).

"유용하고 의미있는"주석에 방법 목표, 규칙 등을 표시하는 것이 좋습니다.

다음과 같이 공허한 주석으로 코드를 작성하는 것은 매우 좋지 않습니다.

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

이것은 아무 쓸모가 없다고 말합니다. 더 나쁜 것은 스타일과 문법이 모두 좋지 않다는 것입니다.

1. 주석은 "This method"또는 "This class"또는 "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 메소드에 대해 생성 된 주석이 가장 좋지 않습니다.

우리의 코딩 표준은 메소드를 오버라이드 할 때, 메소드를 오버라이드 할 때 부모 클래스 나 인터페이스의 문서가 더 이상 서브 클래스 또는 구현 클래스에 대해 정확하고 포괄적이지 않은 한 메소드를 문서화 할 필요가 없다고 명시하고 있습니다.

같으면 데이터베이스 지원 엔터티를 비교할 때 기본 키에서만 수행된다는 점에 유의해야합니다 Object.equals().

내 의견으로는, 이것이 논란의 여지가 있다고 생각하므로, 수업에 어떤 클래스를 재정의했는지에 의견을 표시해야합니다. 그런 다음 6 개월 동안 줄을 지어 구현 여부를 궁금해하면 수업을 열지 않고도 볼 수 있습니다.

이러한 방법이 일반적이며 대부분의 개발자가 자신이 무엇을하는지 알고있을 것입니다. IMO, 의견을 말하지 않아도됩니다. 구현이 업데이트 될 때 업데이트되지 않을 수 있으며 혼동을 일으킬 수 있으므로 주석은 장기적으로 신뢰할 수 없습니다. 따라서 대부분 신뢰할 수있는 코드이므로 코드를 읽을 수있게 만드는 것이 좋습니다.

또한 작성 / 편집중인 코드가 공용 API가 아닌 경우 일반적인 메소드에 대한 javadoc을 제외하면 혼란스럽고 노이즈가 추가됩니다.