документация API и “ограничения по значениям”:совпадают ли они?

Question

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

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

Под "ограничениями ценности" я подразумеваю:

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

Образец:

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

/**
 * 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, они связаны друг с другом или нет?

Answer 1

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

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

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

Answer 2

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

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

Answer 3

Вопрос 1

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

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

Вопрос 2

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

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

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

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

Вопрос 3

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

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

Answer 4

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

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

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

Answer 5

@Огненный Улан:Правильно!Я забыл об exception, но я хотел бы, чтобы они были упомянуты, особенно непроверенное исключение 'runtime', которое может выдавать этот открытый метод

@Майк Стоун:

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

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

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

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

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

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

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