쓰는 모든 방법에 Javadoc을 사용하십니까? [닫은

https://stackoverflow.com/questions/211041

03-07-2019
|

문제

모든 Java 방법에 대한 DOC 댓글을 작성해야합니까?

해결책

@Claudiu

다른 사람들이 사용할 코드를 작성할 때 - 예. 다른 사람이 사용할 수있는 모든 방법 (모든 공개 방법)은 적어도 명백한 목적을 명시하는 Javadoc을 가져야합니다.

@Daniel Spiewak

모든 API 클래스의 모든 공개 방법을 철저히 문서화합니다. 공개 회원이 있지만 외부 소비를위한 것이 아닌 클래스는 클래스 Javadoc에 두드러지게 표시됩니다. 또한 모든 API 클래스에서 모든 보호 방법을 문서화하지만 적은 정도로 문서화합니다. 이는 API 클래스를 확장하는 개발자가 이미 무슨 일이 일어나고 있는지에 대한 공정한 개념을 가지고 있다는 생각이 나옵니다.

마지막으로, 나는 때때로 내 자신의 혜택을 위해 개인 및 개인 사유 방법을 문서화 할 것입니다. 사용에 대한 설명이 필요하다고 생각하는 모든 방법이나 필드는 가시성에 관계없이 문서를 받게됩니다.

@paul de vrieze

사소한 getters 및 setters와 같은 것들에 대해서는 그 사이의 의견을 공유하고 Getter/Setter가 아닌 속성의 목적을 설명하십시오.

/** 
 * Get the current value of the foo property.
 * The foo property controls the initial guess used by the bla algorithm in
 * {@link #bla}
 * @return The initial guess used by {@link #bla}
 */
int getFoo() {
  return foo;
}

그리고 네, 이것은 더 많은 일입니다.

@vonc

거대한 복잡한 방법을 깨뜨릴 때 ( 높은 순환 복잡성 이유) :

하나의 공개 방법 호출
대중의 내부 단계를 나타내는 몇 가지 개인 방법

, Javadoc API 파일에서 해당 문서가 표시되지 않더라도 개인 메소드를 Javadoc에게도 매우 유용합니다.
그럼에도 불구하고 복잡한 알고리즘의 다른 단계의 정확한 특성을 더 쉽게 기억할 수 있습니다.

그리고 기억하십시오 : 값 또는 경계 조건을 제한합니다 Javadoc의 일부가되어야합니다.

을 더한, Javadoc은 단순한 "// comment"보다 훨씬 낫습니다.:

그것은 IDE에 의해 인식되며 커서를 javadoc -ed 함수 중 하나 위에 움직일 때 팝업을 표시하는 데 사용됩니다. 예를 들어, a 끊임없는 - 개인 정적 최종 변수 - 특히 값이 사소하지 않은 경우 Javadoc을 가져야합니다. 지목 사항: Regexp (Javadoc은 regexp를 eScaped 형태로 포함해야합니다.
외부 도구 (예 : xdoclet)

@domci

나를 위해, 누군가가 그것을 보거나 상관 없다면 - 나는 몇 달 후에 내가 쓴 모호한 코드 조각이 무엇을하는지 알지 못할 것입니다. [...
간단히 말해서, 구문이 아닌 논리로 논리를하고 적절한 장소에서 한 번만하십시오.

@Miguel Ping

무언가를 말하려면 먼저 이해해야합니다. 함수를 주석하려고 할 때 실제로 메소드/기능/클래스가하는 일을 생각하고 있으며, 이는 Javadoc에서보다 구체적이고 명확하게 만들어서 더 명확하고 간결한 코드를 작성하게합니다. .

다른 팁

이 방법이 분명히 자기 분명하다면 Javadoc 주석을 건너 뛸 수 있습니다.

댓글이 좋아요

/** Does Foo */
 void doFoo();

정말 유용하지 않습니다. (지나치게 단순한 예이지만 아이디어를 얻습니다)

나 철저히 모든 API 클래스의 모든 공개 방법을 문서화하십시오. 공개 회원이 있지만 외부 소비를위한 것이 아닌 클래스는 클래스 Javadoc에 두드러지게 표시됩니다. 또한 모든 API 클래스에서 모든 보호 방법을 문서화하지만 적은 정도로 문서화합니다. 이는 API 클래스를 확장하는 개발자가 이미 무슨 일이 일어나고 있는지에 대한 공정한 개념을 가지고 있다는 생각이 나옵니다.

마지막으로, 나는 때때로 내 자신의 혜택을 위해 개인 및 개인 사유 방법을 문서화 할 것입니다. 사용에 대한 설명이 필요하다고 생각하는 모든 방법이나 필드는 가시성에 관계없이 문서를 받게됩니다.

사소한 getters 및 setter와 같은 것들에 대해서는 그 사이의 의견을 공유하고 Getter/Setter가 아닌 속성의 목적을 설명하십시오.

/** 
 * Get foo
 * @return The value of the foo property
 */
int getFoo() {
  return foo;
}

~이다 유용하지 않다. 다음과 같은 작업을 수행하는 것이 좋습니다.

/** 
 * Get the current value of the foo property.
 * The foo property controls the initial guess used by the bla algorithm in
 * {@link #bla}
 * @return The initial guess used by {@link #bla}
 */
int getFoo() {
  return foo;
}

그리고 네, 이것은 더 많은 일입니다.

모든 기지는 이미 다른 기지에 포함됩니다. 추가 참고 사항 :

당신이 이것을하고 있다면 :

/**
 * This method currently launches the blaardh into the bleeyrg.
 */
void execute() { ... }

이것으로 바꾸는 것을 고려하십시오.

void launchBlaardhIntoBleeyrg() { ... }

이것은 조금 분명해 보일 수 있지만 많은 경우에 기회는 자신의 코드에서 쉽게 놓칠 수 있습니다.

마지막으로 변화는 그렇지 않다는 것을 명심하십시오 언제나 원한다; 예를 들어,이 방법의 동작은 시간이 지남에 따라 진화 할 것으로 예상 될 수있다 (Javadoc에서 "현재"라는 단어에 주목).

아니요, 모든 방법, 가변, 클래스 등 모든 방법을 언급하지 마십시오.

다음은 "Clean Code : Agile Software Craftsmansib의 핸드북"의 인용문입니다.

모든 함수에 javadoc이 있어야한다는 규칙을 갖는 것은 바보 같은 일입니다. 또는 모든 변수에는 주석이 있어야합니다. 이와 같은 의견은 코드를 혼란스럽게하고, 포가 게이트 거짓말을하고, 일반적인 혼란과 무질서에 빌려줍니다.

만약 주석이 존재해야하며 예정된 방법, 가변, 클래스 등의 사용자. "중요한"을 구성하는 것은 고려해야 할 가치가 있으며,이 메소드/클래스 등으로 돌아 오면 방법의 결과/부작용 인 경우 나 자신을 상기시킬 수 있습니다. , 사물이 존재하는 이유에 대한 동기 (일부 코드가 일부 라이브러리 또는 시스템의 단점/버그를 극복하는 경우), 성능에 대한 중요한 정보 또는 전화하기에 적합한 경우 등에 대한 동기 부여.

무엇인가요 ~ 아니다 좋은 의견은 코드 자체를 다시 작성/수정해야한다는 것을 나타냅니다. 복잡하고 모호한 방법이나 기능의 세부 사항을 설명하는 의견입니다. 대신 더 짧은 명확한 코드를 선호하십시오.

Javadocs를 사용해야하는 또 다른 이유가 있습니다. 무언가를 말하려면 먼저 이해해야합니다. 함수를 댓글을 달려고 할 때는 실제로 생각 방법/기능/클래스가하는 일에 대해, 이것은 당신이 당신의 Javadoc에서 더 구체적이고 명확하게 만들어 지므로, 이로 인해 더 명확하고 간결한 코드를 작성하게합니다.

내가 나 자신을 위해 코드를 쓸 때 - 아니. 이 경우 Java Doccing은 내 시간의 낭비입니다.

다른 사람들이 사용할 코드를 작성할 때 - 예. 다른 사람이 사용할 수있는 모든 방법 (모든 공개 방법)에는 적어도 명백한 목적을 명시하는 Java Doc이 있어야합니다. 좋은 테스트를 위해 - 코드에서 Javadoc Creation 유틸리티를 실행하십시오 (지금 정확한 명령 줄을 잊어 버리십시오). 생성하는 웹 페이지를 찾아보십시오. 해당 수준의 문서가있는 라이브러리를 사용하는 것이 만족한다면 황금빛입니다. 그렇지 않다면 코드에 더 많은 Javadoc을 작성하십시오.

나를 위해, 누군가가 그것을 보거나 상관 없다면 - 나는 몇 달 후에 내가 쓴 모호한 코드 조각이 무엇을하는지 알지 못할 것입니다. 몇 가지 지침이 있습니다.

API, 프레임 워크 클래스 및 내부 재사용 가능한 정적 메소드는 철저히 주석해야합니다.
모든 복잡한 코드 조각의 논리는 Javadoc의 일반 논리와 자체 주석의 각 의미있는 부분에 대한 논리의 두 곳에서 설명해야합니다.
모델 속성은 명확하지 않은 경우 주석을 주어야합니다. 예를 들어, 사용자 이름과 비밀번호를 댓글을 달리는 것은 없지만 유형은 적어도 유형의 가능한 값이 무엇인지 알 수있는 주석을 가져야합니다.
나는 "책에 의해"Getters, Setters 또는 수행 된 모든 것을 문서화하지 않습니다. 팀이 양식, 어댑터, 컨트롤러, 정면을 만드는 표준 방법을 가지고 있다면 ... 모든 어댑터가 동일하고 표준 방법 세트가있는 경우에는 아무런 의미가 없기 때문에 문서화하지 않습니다. 프레임 워크에 익숙한 사람은 프레임 워크 철학과 작업 방식이 어딘가에 문서화되어 있다고 가정 할 때 자신이 무엇을 해야하는지 알 것입니다. 이 경우 의견은 추가 혼란을 의미하며 목적이 없습니다. 클래스가 비표준을 수행 할 때 이에 대한 예외가 있습니다. 그러면 짧은 주석이 유용합니다. 또한 표준 방식으로 양식을 작성하더라도 코드를 여러 부분으로 나누는 짧은 주석으로 양식의 일부를 나누는 것을 좋아합니다 (예 : 청구 주소가 여기에서 시작됩니다”.

간단히 말해서, 구문이 아닌 논리로 논리를하고 적절한 장소에서 한 번만하십시오.

Java Doc은 코드뿐만 아니라 Java Doc을 유지하기 위해 변경하는 개발자에게 부담을주기 때문에 의존해서는 안됩니다.

클래스 이름과 기능 이름은 무슨 일이 일어나고 있는지 설명 할만 큼 충분히 명시되어야합니다.

클래스 나 방법이 무엇을하는지 설명하려면 이름이 너무 길어지면 클래스 나 방법이 충분히 집중되지 않으며 더 작은 단위로 리팩토링되어야합니다.

간단히 말해 : 예

문서를 작성 해야하는지에 대해 생각해야 할 시간은 문서 작성에 더 잘 투자됩니다.

한 라이너를 작성하는 것이 결국 방법을 전혀 문서화하지 않는 데 시간을 소비하는 것보다 낫습니다.

허용되는 매개 변수에 대한 의견이 있어야한다고 생각하고 그 용어로 반환 유형이 반환됩니다.
함수 이름이이를 완전히 설명하는 경우 구현 세부 사항을 건너 뛸 수 있습니다. 이메일을 보내(..);

모든 방법을 실제로 문서화해야 할 것입니다. 가장 중요한 것은 공개 API 방법 (특히 게시 된 API 방법)입니다. 개인적 방법은 때때로 문서화되지 않지만 명확성을 위해서는 그렇습니다. 보호 된 방법과 마찬가지로 동일합니다. 귀하의 의견은 유익해야하며 코드가하는 일을 반복하는 것이 아닙니다.

방법이 특히 복잡한 경우 문서화하는 것이 좋습니다. 어떤 사람들은 코드가 주석이 필요하지 않도록 명확하게 작성되어야한다고 생각합니다. 그러나 이것이 항상 가능한 것은 아니므로 주석을 사용해야합니다.

코드 템플릿을 통해 Eclipse의 Getters/Setter에 대한 Javadoc 주석 생성을 자동화하여 작성 해야하는 문서의 양을 저장할 수 있습니다. 또 다른 팁은 @{$ inheritdoc}를 사용하여 인터페이스와 구현 클래스 간의 코드 주석의 복제를 방지하는 것입니다.

Javadoc은 라이브러리 및 재사용 가능한 구성 요소에 정말 유용 할 수 있습니다. 그러나 더 실용적으로합시다. Javadoc보다 자기 설명 코드를 갖는 것이 더 중요합니다. Javadocs와의 거대한 레거시 프로젝트를 상상한다면 - 당신은 그것에 의존 하시겠습니까? 나는 그렇게 생각하지 않습니다 ... 누군가가 Javadoc을 추가 한 다음 구현이 변경되었고, 새로운 기능이 추가 (제거)되어 Javadoc이 쓸모 없게되었습니다. 내가 언급했듯이 나는 도서관을위한 Javadocs를 좋아하지만 활발한 프로젝트의 경우 선호합니다.

그들이하는 일을 설명하는 이름이있는 작은 기능/클래스
기능/클래스가 무엇을하는지 설명하는 명확한 단위 테스트 케이스

이전 회사에서는 Eclipse와 함께 Jalopy Code Formatter를 사용했습니다. 그것은 개인을 포함한 모든 방법에 Javadoc을 추가 할 것입니다.

세터와 게터를 문서화하기가 어려워졌습니다. 그러나 도대체. 당신은 그것을해야합니다 - 당신은 그것을합니다. 그로 인해 Xemacs를 사용하여 매크로 기능을 배우게되었습니다. :-) 당신은 몇 년 전에 Antlr Creator와 같은 Java Parser와 Commenter를 작성하여 더욱 자동화 할 수 있습니다. :-).

현재 저는 모든 공개 방법과 10 줄 이상을 문서화합니다.

나는 사소한 일 때마다 javadoc 댓글을 작성하는 것이 중요합니다. 게다가, 당신이 Javadoc 의견을 쓸 때, 당신은 방법이 무엇을하는지뿐만 아니라 방법이 무엇을하는지에 대해 생각해야합니다. 바로 그거죠, 그리고 당신이 만든 가정.

또 다른 이유는 코드를 이해하고 리팩토링되면 Javadoc을 사용하면 언제든지 참조 할 수 있기 때문에 그것이 무엇을하는지 잊을 수 있기 때문입니다. 나는 당신의 방법이 무엇을하는지 의도적으로 잊어 버리는 것을 옹호하는 것이 아니라 더 중요한 다른 것들을 기억하는 것을 선호하는 것입니다.

Javadoc 의견이없는 코드에 대해 Javadoc을 실행할 수 있으며 방법과 매개 변수에 신중한 이름을 주면 상당히 사용 가능한 Javadoc을 생성합니다.

나는 최소한 모든 공개 및 인터페이스 속성과 방법을 문서화하려고 노력하여 사람들이 내 코드를 호출하는 사람들이 무엇이 무엇인지 알 수 있도록 노력합니다. 또한 유지 보수를 위해 가능한 한 줄을 서서 언급하려고 노력합니다. 내가 나 자신을 위해 내 시간에하는 '개인'프로젝트조차도, 나는 1 년 동안 그것을 선반하고 나중에 다시 돌아올 수 있기 때문에 Javadoc을 시도합니다.

지금까지 모든 답변에서 의견은 좋은 의견이 될 것이라고 가정합니다. 우리 모두가 항상 사실이 아니라는 것을 알고 있듯이 때로는 잘못된 것도 아닙니다. 의도, 경계 및 예상 오류 동작을 결정하기 위해 코드를 읽어야하는 경우 주석이 부족합니다. 예를 들어, 메소드 스레드 SAFE는 ARG가 NULL 일 수 있으며 NULL 등을 반환 할 수 있습니다. 주석은 모든 코드 검토의 일부 여야합니다.

코드베이스의 관리자는 API 사용자가하지 않을 문제와 경쟁해야하므로 개인 방법에 더욱 중요 할 수 있습니다.

아마도 IDES에는 개발자가 현재 방법에 중요하고 적용 할 수있는 다양한 속성을 확인할 수 있도록 문서화 양식을 사용할 수있는 기능이 있어야합니다.

라이센스 : CC-BY-SA ~와 함께 속성

제휴하지 않습니다 StackOverflow