Документация логики в javadoc

Question

У меня вопрос о том, где документировать логику в javadocs. Например, у меня есть следующий метод подписи в интерфейсе:

public int getTotalAssociationsAsParent(Long id, Long type); 

Метод возвращает ассоциации, где данный идентификатор родитель и ассоциация типа «типа». ID требуется, но если тип передан в NULL, тогда я верну ВСЕ ассоциации, где идентификатор является родительским.

Мой вопрос: где должен быть документирован этот тип логики? Я стесняюсь помещать его в javadoc интерфейса, потому что это ограничивает все реализующие классы, чтобы придерживаться этой логики. Возможно, в будущем у меня будет класс Impl, который генерирует исключение IllegalArgumentException, если тип NULL.

Однако, если я поместил его в не-javadoc в классе Impl, то потребители этого метода не будут знать, как метод ведет себя с типом NULL.

Answer 1

То, что вы описываете, является интерфейсным контрактом метода, поэтому оно действительно принадлежит Javadoc. Клиентам интерфейса необходимо знать точный контракт, выполняемый этим интерфейсом. Если производный класс реализует метод по-разному, он эффективно нарушает контракт, таким образом разбивая Liskov Substitution Principle.

Однако, если вы чувствуете, что на самом деле место для различных реализаций этого метода, у вас есть несколько вариантов:

• переосмыслить свой дизайн - возможно, эти реализации не должны быть в подклассах одного и того же интерфейса, или, может быть, Вам понадобятся два различных метода в этом интерфейсе
• определить контракт свободно, чтобы разрешить некоторые различия в реализации (но только если это имеет смысл с точки зрения клиентов!)

Answer 2

вы должны описать то, что он будет повторно обратиться к клиенту в каком случае. Клиенту не нужно знать, как вы его обрабатываете, но он должен знать с некоторыми типами ввода, будет возвращен какой-то специальный выход.

В будущем, если вы хотите бросить исключение, вы должны изменить свой Javadoc так, чтобы абонент мог знать, он должен обрабатывать исключение

Answer 3

В общем вы положили это на интерфейс, интерфейс определяет поведение реализаций. Однако здесь нет жесткого и быстрого правила, если какая-то конкретная реализация ведет себя по-другому, вы можете также разделить эту разницу на комментарий реализации. Это очень похоже на то, как Java Standard Library делает вещи в своем JavaDoc.

Рассмотрим, например, ArrayList:

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

имеет RemoveAll, который определен в списке и реализованный в AbstractCollection

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)

в списке определяет класс что он делает, класс AbstractCollection определяет его особое поведение.

Документы - это инструмент, поэтому используйте их по своему усмотрению, самая важная часть этого инструмента заключается в том, что они сохраняются в актуальном состоянии - поэтому над документированием может возникнуть головная боль позже, при документировании тоже! В общем, попробуйте сохранить код, который вы пишете в каждом методе, краткое и краткое и максимально свободное от побочных эффектов, таким образом, вы сможете прочитать код и понять, что это значит делать, не так сильно завися от окружающей документации ,

Answer 4

Выглядит идеально подходит для Javadoc:

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

который не является полезным.