간단한 getter/setter 댓글

StackOverflow https://stackoverflow.com/questions/1028967

문제

getters and setters에 의견을주기 위해 어떤 컨벤션을 사용하십니까? 이것은 예를 들어 꽤 오랫동안 궁금한 점입니다.

/**
 * (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) 직원의 급여를 설정합니다. 너무 중복 된 것 같습니다. 이제 나는 당신이 (a) 부분에 더 많은 글을 쓸 수있는 더 복잡한 것을 볼 수 있었지만, 맥락을 제공하기 위해, 대부분의 getters/setter에 대해 문구는 거의 정확히 동일합니다.

간단한 getters/setters의 경우 (a) 부분 또는 (b) 부분 만 채우는 것이 좋습니다.

어떻게 생각해?

도움이 되었습니까?

해결책

나는 보통 세터의 매개 변수 부분을 채우고 getters의 @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 Checking Tools (예 : 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 () 방법은 "Gobbledygook을 설정한다"고 설명합니다.

내가 도울 수 있다면 일반적으로 아무것도 없습니다. 게터와 세터는 자기 설명이어야합니다.

나는 그것이 응답이 아닌 것처럼 들린다는 것을 알고 있지만, 설명이 필요한 것들을 언급하는 데 시간을 사용하려고 노력합니다.

Getters와 Setter가 부작용이 있거나 초기화 이외의 전제 조건이 필요한 경우 댓글을달라고 걱정하는 것만 걱정하고 있습니다 (즉, 데이터 구조에서 항목을 제거하거나 필요한 것을 설정하기 위해 X와 Y를 먼저 제자리에 두려면). 그렇지 않으면 여기의 의견은 상당히 중복됩니다.

편집 : 또한 Getter/Setter에 많은 부작용이 관련되어 있다면 Getter/Setter를 변경하여 다른 메소드 이름 (예 : 스택을 위해 푸시 및 팝)을 가질 수 있습니다. 아래의 의견]

의견이 Javadocs (브라우저에서)로 볼 때 사람들이 무엇을보고 싶은지 스스로에게 물어보십시오. 많은 사람들은 문서가 명백하기 때문에 필요하지 않다고 말합니다. 필드가 비공개 인 경우 (개인 분야의 Javadocs를 명시 적으로 켜지 않는 한) 이것은 유지되지 않습니다.

귀하의 경우 :

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

어떤 급여가 표현되는지 명확하지 않습니다. 센트, 달러, 파운드, RMB입니까?

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

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

첫 번째 줄은 높이를 반환한다고 말합니다. 리턴 매개 변수는 높이가 미터입니다.

그들이 필드 값과 getters and setters의 참조를 주석 할 수 있도록 참조 태그 만 포함하지 않는 이유는 무엇입니까?

/**
* 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가 켜진 경우).

이러한 종류의 보일러 플레이트는 사용하여 피할 수 있습니다 프로젝트 Lombok. 필드 변수를 문서화하십시오. private, 그리고 Lombok 주석이 적절하게 문서화 된 getters와 setter를 생성하도록하십시오.

나를 위해,이 혜택만으로는 가치가 있습니다 소송 비용.

나는 기본적으로 포괄적 인 문서화가 시간 낭비라고 말하는 답변에 정말 실망했습니다. API의 클라이언트는 어떻게 setX a 표준 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() 사람의 이름을 반환하지 않습니까?

필드 이름이 내용에 대해 설득력있는 경우 아무것도 넣지 마십시오.

일반적으로 코드를 자체적으로 유지하고 가능한 경우 의견을 피하십시오. 리팩토링이 필요할 수 있습니다.

편집 : 위의 내용은 getters and setter만을 나타냅니다. 나는 사소한 것이 없다고 생각합니다.

(b) 부분을 채워도 괜찮습니다. 특히 필드 선언에 필드가 무엇인지를 나타내는 의견을 제시하는 경우.

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

나는 항상 두 가지를 채 웁니다. 타이핑을 추가로 소비하는 추가 시간은 무시할 수 있으며 일반적으로 더 많은 정보가 적습니다.

Getter/Setter 인 경우 문서화해야합니다.

나는 여기서 쫓아 내지 만, 그것이 재산을 만들 수 있다면, 아마도 수업 사용자의 더 간단한 코딩에 더 좋습니다. 나는 더 멀리 다가 오지만 어디에나 "java"가있는 모든 의견은 누가 Java라고 말 했습니까? (태그이지만 질문은 실제로 어디서나 적용될 수 있습니다)

라이센스 : CC-BY-SA ~와 함께 속성
제휴하지 않습니다 StackOverflow
scroll top