api 文档和“值限制”：他们匹配吗？

Question

您是否经常在 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，它们是否属于一起？

Answer 1

我觉得他们 能 属于在一起但不一定 有 属于在一起。在您的场景中，限制以出现在生成的 API 文档和智能感知中的方式记录似乎是有意义的（如果语言/IDE 支持它）。

我认为这也取决于语言。例如，Ada 的本机数据类型是“受限整数”，您可以在其中定义整数变量并明确指示它仅（且始终）位于某个数值范围内。在这种情况下，数据类型本身表明了限制。它应该仍然可以通过 API 文档和智能感知可见和发现，但开发人员不必在注释中指定。

然而，像 Java 和 C# 这样的语言没有这种类型的受限整数，因此如果它是应成为公共文档一部分的信息，则开发人员必须在注释中指定它。

Answer 2

我认为这些边界条件绝对属于 API。然而，我会（而且经常）更进一步指出这些空值的含义。要么我指示它将抛出异常，要么我解释传入边界值时的预期结果是什么。

记住总是这样做是很困难的，但这对于你的班级的用户来说是一件好事。如果方法呈现的合同发生更改（例如将空值更改为不允许），那么维护它也很困难...当您更改方法的语义时，您还必须勤奋地更新文档。

Answer 3

问题1

您是否经常在 API 文档（例如“公共函数的 javadoc”）中看到“值限制”以及经典文档的描述？

几乎从不。

问题2

当我想使用这个功能时我唯一关心的是：我应该期望什么参数和返回值？这就是我安全设置参数和安全测试返回值所需知道的全部内容，但我几乎从未在 API 文档中看到此类信息......

如果我不正确地使用一个函数，我会期望 RuntimeException 由方法或a抛出 RuntimeException 在程序的另一个（有时很远）部分。

评论喜欢 @param aReaderNameRegexp filter in order to ... (can be null or empty) 在我看来是一种实施方式 合同设计 在里面用人类语言 Java文档.

使用 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

@火枪手：正确的！我忘记了异常，但我希望看到它们被提及，特别是此公共方法可能抛出的未经检查的“运行时”异常

@迈克·斯通：

当您更改方法的语义时，您还必须勤奋地更新文档。

嗯，我当然希望 公共API文档 至少每当发生影响函数契约的更改时都会更新。如果没有，这些 API 文档可能会被完全删除。

为了给你的想法添加食物（并与@Scott Dorman一起），我只是偶然发现 java7注解的未来

这意味着什么？某些“边界条件”，而不是在文档中，应该在 API 本身中更好，并在编译时自动使用适当的“断言”生成的代码。

这样，如果 API 中存在“@CheckForNull”，函数的编写者可能甚至不需要记录它！如果语义发生变化，其 API 将反映该变化（例如“不再使用 @CheckForNull”）

这种方法表明，“边界条件”的记录是额外的好处，而不是强制性的做法。

但是，这不包括函数返回对象的特殊值。为此，一个 完全的 仍然需要文档。