API-документация и «пределы стоимости»: они совпадают?

Question

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

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

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

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

Пример:

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

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

Вопрос 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, но я согласен с вами в том, что вы должны знать о Когда выбирать отмеченные и непроверенные исключения . Возможно, вы можете использовать непроверенные IllegalArgumentException, IllegalStateException или использовать модульное тестирование, но основная проблема заключается в том, как сообщить другим программистам, что такой код предназначен для Design By Contract и должен рассматриваться как контракт, прежде чем изменять его. легко.

Answer 3

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

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

Answer 4

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

@ Майк Стоун:

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

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

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

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

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

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

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

Answer 5

Я думаю, что они делают, и всегда размещали комментарии в заголовочных файлах (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);