6

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

4

5 回答 5

5

我认为他们可以属于一起，但不一定必须属于一起。在您的场景中，似乎有必要将限制记录在生成的 API 文档和智能感知中（如果语言/IDE 支持它）。

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

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

于 2008-09-14T20:21:57.417 回答
2

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

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

于 2008-09-14T20:19:06.613 回答
2

问题 1

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

几乎从不。

问题2

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

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

在我看来，像这样的评论是一种在Javadoc中以人类语言@param aReaderNameRegexp filter in order to ... (can be null or empty)实现按合同设计的方法。

使用 Javadoc 来执行按合同设计iContract，现在已重新使用JcontractS，它允许您以比人类语言更正式的方式指定不变量、前置条件、后置条件。

问题 3

这可能会影响已检查或未检查异常的使用或不使用。你怎么看 ？值限制和 API，它们是否属于一起？

Java 语言没有按合同设计的特性，因此您可能会很想使用Execption，但我同意您的观点，即您必须了解何时选择已检查和未检查的异常。可能您可能会使用 unchecked IllegalArgumentException, IllegalStateException，或者您可能会使用单元测试，但主要问题是如何与其他程序员沟通此类代码是关于按合同设计的，并且在更改它之前应该将其视为合同。

于 2014-06-14T20:46:09.043 回答
1

我认为他们这样做，并且总是在头文件（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);
于 2008-09-14T20:18:26.567 回答
1

@Fire Lancer：对！我忘记了异常，但我希望看到它们被提及，尤其是这个公共方法可能抛出的未经检查的“运行时”异常

@迈克·斯通：

当您更改方法的语义时，您还必须努力更新文档。

嗯，我当然希望公共 API 文档至少在发生更改（影响函数合同）时进行更新。如果没有，这些 API 文档可能会被完全删除。

为了给你的想法添加食物（和@Scott Dorman一起去），我偶然发现了java7注释的未来

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

这样，如果 API 中有一个“@CheckForNull”，那么函数的编写者可能会侥幸逃脱，甚至不记录它！如果语义发生变化，它的 API 将反映这种变化（例如“不再有 @CheckForNull”）

这种方法表明，对于“边界条件”，记录是一种额外的奖励，而不是强制性的做法。

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

于 2008-09-14T20:43:42.780 回答