간단한 Getter/Setter 코멘트

간단한 Getter/Setter 코멘트

getters와 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에 대해 거의 같은 내용을 쓰고 있다는 것을 알게 됩니다. 예를 들어 1) 직원의 급여를 설정합니다. 1) 직원의 급여를 설정합니다.그냥 너무 중복된 것 같아.(a) 부분에 더 많은 내용을 적어 컨텍스트를 제공할 수도 있지만, 대부분의 getter/setters에서는 거의 동일한 표현을 사용합니다.

단순한 getter/setters의 경우 (a) 부분 또는 (b) 부분 중 하나만 입력해도 되는지 궁금할 뿐입니다.

당신은 어떻게 생각하나요?

전혀 무의미해 - 코드를 어지럽히는 이런 종류의 쓰레기는 없는 게 좋아.

/**
 * 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);

특히 도메인 모델에서는 속성이 실제로 무엇을 의미하는지 설명하는 것이 중요합니다.투자은행가, 생화학자, 양자물리학자들만 이해하는 이름 불명확한 속성들이 가득하고, setGobbledykuk() 메서드가 "set gobbledykuk"라고 설명되는 것을 볼 때마다 누군가의 목을 조르고 싶다.

보통 setters의 param 부분과 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 체크 툴(Eclipse 경고 등)이 깨끗해지고 중복이 발생하지 않습니다.

내가 도울 수 있다면 대개는 아무것도 하지 않는다.Getters와 Setters는 스스로 설명해야 합니다.

무응답처럼 들리겠지만, 저는 설명이 필요한 것들을 코멘트하는 데 시간을 쓰려고 합니다.

getters와 setters가 어떤 부작용이 있거나 초기화 이외의 전제조건이 필요한 경우(즉, getters를 취득하면 데이터 구조에서 항목이 삭제되거나 x와 y를 먼저 설정해야 하는 경우)에만 코멘트를 할 수 있습니다.그렇지 않으면 여기의 코멘트는 꽤 중복된다.

편집: 또한 getter/setter에 많은 부작용이 있는 경우 getter/setter를 다른 메서드 이름으로 변경할 수 있습니다(즉, 스택의 push and pop). [아래 코멘트 감사합니다]

주석이 JavaDocs로 표시될 때(브라우저에서) 사용자에게 무엇을 보여주기를 원하는지 자문해 보십시오.증빙 서류는 명백하기 때문에 필요하지 않다고 말하는 사람이 많습니다.필드가 개인 필드인 경우(개인 필드에 대해 JavaDocs를 명시적으로 설정하지 않는 한) 이 작업은 유지되지 않습니다.

고객님의 경우:

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

급여가 무엇으로 표현되는지는 명확하지 않다.센츠, 달러, 파운드, 위안화?

setters/getters를 문서화할 때 인코딩에서 무엇을 분리하는 것을 좋아합니다.예:

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

첫 번째 줄에는 높이가 반환된다고 되어 있습니다.높이가 미터 단위인 반환 매개 변수 문서입니다.

필드 값과 getters 및 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가 켜져 있는 경우)에 적용됩니다.

Project Lombok을 사용하면 이러한 종류의 보일러 플레이트를 피할 수 있습니다.필드 변수만 문서화하면 됩니다.private롬복 세터

저는 이 혜택만으로도 비용을 들일 가치가 있습니다.

포괄적인 문서화는 시간 낭비라는 답변에 정말 실망했습니다.는 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()사람의 이름을 돌려주지 않는다...그럼, 거기 가지 맙시다, 응?

필드명이 내용을 알기 쉽게 기술하고 있는 경우는, 아무것도 넣지 말아 주세요.

일반적으로 코드는 자기스탠딩으로 하고 가능하면 코멘트를 하지 않도록 합니다.리팩터링이 필요할 수 있습니다.

편집: 위는 getter와 setter만을 나타냅니다.사소한 것이 아닌 것은 적절히 javadoc'해야 한다고 생각합니다.

(b) 부분을 입력해도 괜찮습니다. 특히 필드 선언에 필드에 대한 모든 내용을 나타내는 주석을 넣는 경우입니다.

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

저는 항상 둘 다 채웁니다.입력에 소요되는 추가 시간은 무시할 수 있으며, 일반적으로 더 많은 정보가 더 적은 것보다 더 좋습니다.

언급URL : https://stackoverflow.com/questions/1028967/simple-getter-setter-comments