간단한 Getter / Setter 주석

getter 및 setter에 주석을 달기 위해 어떤 규칙을 사용합니까? 이것은 예를 들어 꽤 오랫동안 궁금해했던 것입니다.

/**
 * (1a) what do you put here?
 * @param salary (1b) what do you put here?
 */
public void setSalary(float salary);

/*
 * (2a) what do you put here?
 * @return (2b)
 */
public float getSalary();

나는 항상 1a / b와 2a / b에 대해 거의 똑같은 것을 쓰고 있다는 것을 알았습니다. 1a) 직원의 급여를 설정하고 1b) 직원의 급여를 설정합니다. 너무 중복되는 것 같습니다. 이제 더 복잡한 것을 볼 수 있습니다. (a) 부분에 더 많이 작성하여 컨텍스트를 제공 할 수 있지만 대부분의 getter / setter에 대한 표현은 거의 동일합니다.

간단한 게터 / 세터의 경우 (a) 부분 또는 (b) 부분 만 채우는 것이 괜찮은지 궁금합니다.

어떻게 생각해?

저는 보통 setter의 경우 param 부분을 채우고 getter의 경우 @return 부분을 채 웁니다.

/**
 * 
 * @param salary salary to set (in cents)
 */
public void setSalary(float salary);

/**
 * @return current salary (in cents, may be imaginary for weird employees)
 */
public float getSalary();

그렇게하면 javadoc 검사 도구 (예 : Eclipse의 경고)가 깔끔하게 나오고 중복이 없습니다.

절대적으로 무의미합니다. 이런 종류의 쓰레기가 코드를 어지럽히 지 않는 것이 좋습니다.

/**
 * Sets the foo.
 * 
 * @param foo the foo to set
 */
public void setFoo(float foo);

보증되는 경우 매우 유용합니다.

/**
 * Foo is the adjustment factor used in the Bar-calculation. It has a default
 * value depending on the Baz type, but can be adjusted on a per-case base.
 * 
 * @param foo must be greater than 0 and not greater than MAX_FOO.
 */
public void setFoo(float foo);

특히 속성이 실제로 의미하는 바에 대한 설명은 도메인 모델에서 중요 할 수 있습니다. 투자 은행가, 생화학 자 또는 양자 물리학 자만 이해하는 모호한 이름의 속성으로 가득 찬 콩을 볼 때마다 setGobbledygook () 메서드가 "구 블디 국을 설정"한다고 설명 할 때마다 누군가 목을 졸라 매고 싶습니다.

내가 도울 수 있다면 일반적으로 아무것도 아닙니다. 게터와 세터는 자명해야합니다.

답이없는 것처럼 들리지만 설명이 필요한 부분에 대해 설명하는 데 시간을 사용하려고합니다.

getter와 setter에 일종의 부작용이 있거나 초기화 외부의 전제 조건이 필요한 경우에만 주석을다는 것에 대해 걱정한다고 말하고 싶습니다 (예 : 데이터 구조에서 항목을 제거하거나 필요한 것을 설정하기 위해 x와 y를 먼저 배치). 그렇지 않으면 여기에있는 주석이 상당히 중복됩니다.

편집 : 또한, getter / setter에 많은 부작용이 관련되어있는 경우 getter / setter를 다른 메서드 이름 (예 : 스택에 대해 푸시 및 팝)으로 변경하고 싶을 수 있습니다. [감사합니다. 아래 댓글]

주석이 JavaDocs (브라우저에서)로 표시 될 때 사람들이 무엇을 보길 원하는지 자문 해보십시오. 많은 사람들은 문서가 뻔하기 때문에 필요하지 않다고 말합니다. 필드가 비공개 인 경우에는 유지되지 않습니다 (개인 필드에 대해 JavaDocs를 명시 적으로 설정하지 않는 한).

귀하의 경우 :

public void setSalary(float s)
public float getSalary()

급여가 무엇으로 표시되는지 명확하지 않습니다. 센트, 달러, 파운드, 인민폐?

setter / getter를 문서화 할 때 인코딩에서 무엇을 분리하고 싶습니다. 예:

/**
 * Returns the height.
 * @return height in meters
 */
public double getHeight()

첫 번째 줄은 높이를 반환한다고 말합니다. 반환 매개 변수는 높이가 미터 단위임을 문서화합니다.

필드 값과 getter 및 setter의 참조를 주석 처리 할 수 ​​있도록 참조 태그를 포함하지 않는 이유는 무엇입니까?

/**
* The adjustment factor for the bar calculation.
* @HasGetter
* @HasSetter
*/
private String foo;

public String getFoo() {
  return foo;
}

public void setFoo() {
  this foo = foo;
}

따라서 문서는 필드뿐만 아니라 getter 및 setter에도 적용됩니다 (개인용 javadocs가 켜져있는 경우).

이러한 종류의 상용구는 Project Lombok 을 사용하여 피할 수 있습니다 . 필드 변수를 문서화하십시오.private 되며 Lombok 주석이 적절하게 문서화 된 getter 및 setter를 생성하도록합니다.

저에게있어이 혜택만으로도 비용의 가치가 있습니다 .

기본적으로 포괄적 인 문서화가 시간 낭비라고 말하는 답변에 대해 정말 실망합니다. API의 클라이언트는 호출 된 메소드 setX가 문서에서 그렇게 명확하게 말하지 않는 한 표준 JavaBean 속성 설정 자임을 어떻게 알 수 있습니까?

문서가 없으면 호출자는 메서드에 부작용이 있는지 알 수 없습니다.

호출 된 메서드 setX가 속성을 설정하는 것보다 훨씬 더 많은 작업을 수행하는 어려운 방법을 알아내는 불행을 겪은 사람은 저 뿐만이 아닙니다.

getter / setter에 특별한 작업이 없으면 일반적으로 다음과 같이 작성합니다.

Javadoc 사용 (개인 옵션 사용) :

/** Set {@see #salary}. @param {@link #salary}. */
public void setSalary(float salary);

및 / 또는

/** 
 * Get {@see #salary}.
 * @return {@link #salary}.
 */
public float salary();

Doxygen 사용 (개인 추출 옵션 사용) :

/** @param[in] #salary. */
public void setSalary(float salary);

/** @return #salary. */
public float salary();

특히 접근 자에 대해 아무 작업도 수행하지 않는 경우 주석을다는 것은 불필요하며 손끝을 낭비합니다.

당신의 코드를 읽는 누군가 person.getFirstName()가 그 사람의 이름 을 반환하는 것을 이해하지 못한다면 , 그를 해고하기 위해 당신의 능력으로 모든 것을 시도해야합니다. 데이터베이스 마법을 사용하고 주사위 몇 개를 던지고 이름을 얻기 위해 이름 비서에게 전화를 걸면 사소한 작업이라고 가정하고 잘 문서화하는 것이 안전합니다.

반면에, 당신 person.getFirstName()이 사람의 이름을 돌려주지 않는다면 ... 글쎄, 거기 가지 말자, 우리?

필드 이름이 내용을 충분히 설명하는 경우 아무것도 입력하지 마십시오.

일반적으로 코드는 자립하고 가능하면 주석 처리를 피하십시오. 리팩토링이 필요할 수 있습니다.

편집 : 위의 내용은 게터와 세터 만 참조합니다. 나는 사소한 것이 아닌 것은 적절하게 javadoc되어야한다고 믿습니다.

(b) 부분을 채우는 것이 좋습니다. 특히 필드 선언에 필드가 무엇인지 나타내는 주석을 넣는 경우에는 더욱 그렇습니다.

javadoc이 아무것도 추가하지 않으면 javadoc을 삭제하고 자동 생성 된 주석을 사용합니다.

나는 항상 둘 다 작성합니다. 입력에 소요되는 추가 시간은 무시할 수 있으며 일반적으로 정보가 많을수록 더 좋습니다.