javadoc의 논리 문서화

Question

javadocs에서 논리를 문서화 할 위치에 관한 질문이 있습니다. 예를 들어, 내가 인터페이스에 다음 메소드 서명이 있습니다

public int getTotalAssociationsAsParent(Long id, Long type); 

방법은 주어진 ID는 부모 협회를 반환하고 연결 유형 '형'이다. ID가 필요하지만 전달 된 유형이 NULL이면 ID가 상위 인 모든 연관을 반환합니다.

내 질문에이 논리 유형을 문서화해야합니까? 인터페이스의 javadoc에 넣는 것을 주저합니다. 왜냐하면 그런 종류의 모든 구현 클래스가 해당 논리를 따르도록 제약하기 때문입니다. 미래에는 타입이 NULL이면 IllegalArgumentException을 던질 Impl 클래스가있을 것입니다.

그러나 Impl 클래스의 비 javadoc에 넣으면이 메서드의 소비자는 메서드가 NULL 형식으로 동작하는 방식을 알 수 없습니다.

Answer 1

당신이 묘사하는 것은 그 메소드의 인터페이스 계약이므로 실제로 Javadoc에 속합니다. 인터페이스의 클라이언트는이 인터페이스가 충족시키는 정확한 계약을 알아야합니다. 파생 클래스가 메서드를 다르게 구현하면 계약을 효과적으로 파기하므로 Liskov Substitution Principle이 손상됩니다. - 어쩌면 그 구현이 동일한 인터페이스의 서브 클래스에서, 또는 어쩌면 안

이

• 당신의 디자인을 재고 : 그러나

  , 당신이 정말로이 방법의 다른 구현을위한 장소가 느낀다면, 당신은 몇 가지 선택 사항이 있습니다 당신은 구현의 일부 분산을 할 수 있도록 느슨하게 계약을 정의하는 인터페이스

• 의 두 가지 방법이 필요합니다 (하지만 고객의 관점에서 의미가있는 경우에만!)

Answer 2

당신은 그것을 다시 무슨 설명해야 어떤 경우에 클라이언트를 선택하십시오. 클라이언트는 반환하기 위해 처리하는 방법을 알 필요는 없지만 몇 가지 종류의 입력으로 알아야합니다. 일부 특수 출력이 반환됩니다. 당신이 예외를 throw 할 경우 향후

는, 당신은 발신자가 당신이 인터페이스, 인터페이스 정의에이를 넣어 예외를 일반적으로

Answer 3

을 처리해야 알 수 있도록 자바 독을 변경해야 구현의 동작 그러나 여기에는 아무리 어렵고 빠른 규칙도 없습니다. 특정 구현이 다르게 동작하는 경우 해당 차이를 구현 주석에 넣을 수도 있습니다. 이는 Java 표준 라이브러리가 JavaDoc에서 일을 수행하는 것과 매우 유사합니다.

는, 예를 들어, ArrayList를 생각해

http://java.sun.com/javase/6/docs/api/java/util/ArrayList.html

는 목록에 정의

http://java.sun.com/javase/6/docs/api/java/util/List.html#removeAll(java.util.Collection)

http://java.sun.com/javase/6/docs/api/java/util/AbstractCollection.html#removeAll(java.util.Collection)

List 클래스를 정의 클래스 AbstractCollection에서 구현에서 removeAll을 가지고 그것이 무엇인지, AbstractCollection 클래스는 그것을 정의합니다. 특별한 행동.

문서는 도구이므로 기분에 따라 사용하십시오.이 도구의 가장 중요한 부분은 최신 상태로 유지된다는 것입니다. 문서화가 끝나면 나중에 문서화 할 때 두통이 발생할 수 있습니다. 일반적으로 각 메소드에서 작성한 코드를 가능한 한 부작용이 없도록 짧고 간결하게 유지하십시오. 이렇게하면 주변 문서에 크게 의존하지 않고 코드를 읽고 의미를 이해할 수 있습니다. .

Answer 4

는 자바 독에 대한 완벽한 외모 :

/** 
* The method returns associations where the given ID is the parent and the association is of type 'type'. <br> 
* ID is required, but if type passed in is NULL, then I will return ALL associations where the ID is the parent.<br> 
*<br> 
* Subclasses may throw an IllegalArgumentException if type is NULL.<br> 
* @param id Parent identifier 
* @param type the type of association 
* @return the Association or null if type is null 
*/ 
public int getTotalAssociationsAsParent(Long id, Long type) 

내가 과거에 내 자신에 문서의 종류 있었다 싶습니다.

나는 일반적으로 얻을 : 유용하지 않습니다

/** 
* get the total associations as parent 
* @param id the id 
* @type the type 
*/ 
public int getTotalAssociationsAsParent(Long id, Long type); 

합니다.