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

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

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

Answer 3

Вопрос 1

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

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

вопрос 2

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

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

Комментарии как @param aReaderNameRegexp filter in order to ... (can be null or empty) мне кажется, способ реализовать Design by Contract на человеческом языке внутри 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

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

@ Майк Стоун:

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

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

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

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

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

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

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