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를 생성하도록합니다.
