Документирование логики в javadoc - PullRequest
Новая
       14

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

2 голосов
/ 25 мая 2010

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

public int getTotalAssociationsAsParent(Long id, Long type);

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

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

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

Ответы [ 4 ]

3 голосов
/ 25 мая 2010

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

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

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

Отлично выглядит для 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);

Что бесполезно.

0 голосов
/ 25 мая 2010

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

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

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

имеет removeAll, которое определено в List и реализовано в 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)

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

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

0 голосов
/ 25 мая 2010

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

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

...