документация api и "ограничения ценности": совпадают ли они?

Часто ли вы видите в документации API (например, в "javadoc публичных функций") описание "пределов значений", а также классическую документацию ?

Примечание: я не говорю о комментариях в коде

Под "пределами значений" я подразумеваю:

  • Может ли параметр поддерживать нулевое значение (или пустую строку, или...)?
  • Может ли "возвращаемое значение" быть null или гарантированно никогда не будет null (или может быть "пустым", или...) ?

Пример:

Что я часто вижу (не имея доступа к исходному коду), это: 

/**
 * Get all readers name for this current Report. <br />
 * <b>Warning</b>The Report must have been published first.
 * @param aReaderNameRegexp filter in order to return only reader matching the regexp
 * @return array of reader names
 */
 String[] getReaderNames(final String aReaderNameRegexp);

То, что я хотел бы видеть будет: 

/**
 * Get all readers name for this current Report. <br />
 * <b>Warning</b>The Report must have been published first.
 * @param aReaderNameRegexp filter in order to return only reader matching the regexp 
 * (can be null or empty)
 * @return array of reader names 
 * (null if Report has not yet been published, 
 *  empty array if no reader match criteria, 
 *  reader names array matching regexp, or all readers if regexp is null or empty)
 */
 String[] getReaderNames(final String aReaderNameRegexp);

Моя точка зрения такова:

Когда я использую библиотеку с функцией getReaderNames () в ней, мне часто даже не нужно читать документацию API, чтобы догадаться, что она делает. Но мне нужно быть уверенным , как его использовать.

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

Редактировать:

Это может повлиять на использование или нет для проверенные или непроверенные исключения.

Что вы думаете ? пределы ценности и API, они принадлежат друг другу или нет ?

5 5
language-agnostic documentation comments design-by-contract

5 ответов:

Я думаю, что они могут принадлежать друг другу, но не обязательно должны принадлежать друг другу. В вашем сценарии, похоже, имеет смысл документировать ограничения таким образом, чтобы они отображались в сгенерированной документации API и intellisense (если язык/IDE поддерживают его).

Я думаю, что это также зависит от языка. Например, Ada имеет собственный тип данных, который является "ограниченным целым числом", где вы определяете целочисленную переменную и явно указываете, что он будет только (и всегда) находиться в определенном числовом диапазоне. В этом случае сам тип данных указывает на ограничение. Он по-прежнему должен быть виден и доступен через документацию API и intellisense, но не будет тем, что разработчик должен указать в комментариях.

Однако в таких языках, как Java и C#, нет такого типа ограниченного целого числа, поэтому разработчику пришлось бы указать его в комментариях, если бы это была информация, которая должна стать частью общего доступа. документация.

5

Я думаю, что такие граничные условия наиболее определенно относятся к API. Однако я бы пошел (и часто делаю) дальше и указал, что означают эти нулевые значения. Либо я указываю, что это вызовет исключение, либо объясняю, каковы ожидаемые результаты, когда передается граничное значение.

Трудно всегда помнить об этом, но это хорошо для пользователей вашего класса. Также трудно поддерживать его, если контракт метод представляет изменения (например, null значения изменяются на недопустимые)... вы также должны быть усердны, чтобы обновить документы, когда вы изменяете семантику метода.

2

Вопрос 1

Часто ли вы видите в документации API (например, в "javadoc публичных функций") описание "пределов значений", а также классическую документацию?

Почти никогда.

Вопрос 2

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

Если бы я использовал функцию неправильно, я ожидал бы RuntimeException, брошенную методом или RuntimeException в другой (иногда очень далекой) части программы.

Комментарии типа @param aReaderNameRegexp filter in order to ... (can be null or empty) кажутся мне способом реализации проектирование по контракту на человеческом языке внутриJavadoc .

Использование Javadoc для принудительного исполнения проекта по контракту было использовано iContract, Теперь воскресшим в JcontractS, это позволяет задавать инварианты , предпосылки, постусловия более формализованным способом по сравнению с человеческим языком.

Вопрос 3

Это может повлиять на использование или нет для проверенных или непроверенных исключений. А ты как думаешь ? пределы ценности и API, они принадлежат друг другу или нет ?

Язык Java не имеет функции проектирования по контракту, поэтому у вас может возникнуть соблазн использовать Execption, но я согласен с вами о том, что вы должны знать о , когда выбирать проверенные и непроверенные исключения. Возможно, вы могли бы использовать unchecked IllegalArgumentException, IllegalStateException, или вы можете использовать модульное тестирование, но основная проблема заключается в том, как сообщить другим программистам, что такой код предназначен для разработки по контракту и должен рассматриваться как контракт, прежде чем изменять его слишком легко.

2

Я думаю, что они делают, и всегда размещали комментарии в заголовочных файлах (c++) arcordingly.

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

//File:
// Should be a path to the teexture file to load, if it is not a full path (eg "c:\example.png") it will attempt to find the file usign the paths provided by the DataSearchPath list
//Return: The pointer to a Texture instance is returned, in the event of an error, an exception is thrown. When you are finished with the texture you chould call the Free() method.
//Exceptions:
//except::FileNotFound
//except::InvalidFile
//except::InvalidParams
//except::CreationFailed
Texture *GetTexture(const std::string &File);
1

@Fire Lancer: Верно! Я забыл об исключениях, но я хотел бы, чтобы они упоминались, особенно непроверенное исключение "runtime", которое этот открытый метод может бросить

@Mike Stone:

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

Мммм я очень надеюсь, чтопубличная документация API по крайней мере обновляется всякий раз, когда происходит изменение, которое влияет на контракт функции. Если нет, то эти документы API могут быть вообще отброшены.

Чтобы добавить пищу для ваших мыслей (и пойти с @Scott Dorman), я просто натыкаюсь на будущее java7 аннотации

Что это значит ? Что определенные "граничные условия", вместо того, чтобы быть в документации, должны быть лучше в самом API и автоматически использоваться во время компиляции с соответствующим сгенерированным кодом "assert".

Таким образом, если' @CheckForNull ' находится в API, писатель функции может сойти с рук даже не документирование его! И если семантическое изменение, его API будет отражать это изменение (например, 'no more @CheckForNull')

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

Однако это не распространяется на специальные значения возвращаемого объекта функции. Для этого по-прежнему необходима полная документация .

1