Question

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

“价值限制”，我的意思是：

参数是否可以支持空值（或空字符串，或......）？
“返回值”是否可以为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文档中看到这种信息...

修改：

这可能会影响 checked or unchecked exceptions 的使用情况。

你怎么看？价值限制和API，它们是否属于一起？

Answer 1

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

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

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

Answer 2

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

很难记住总能做到这一点，但这对你班级的用户来说是件好事。如果方法提出的合同发生了变化（比如将空值更改为不允许），那么维护它也很困难......当你改变方法的语义时，你也必须努力更新文档。

Answer 3

问题1

您是否经常在API文档中看到（例如公共函数的javadoc＆＃39;例如）＆＃34;值限制＆＃34;以及经典文档？

几乎没有。

问题2

我想要使用此功能时唯一关心的问题是：在参数和返回值方面我应该期待什么？这就是我需要知道的安全设置我的参数并安全地测试返回值，但我几乎从未在API文档中看到这种信息...

如果我没有正确使用某个函数，我希望该方法抛出RuntimeException，或者在程序的另一个（有时非常远）部分抛出RuntimeException。

@param aReaderNameRegexp filter in order to ... (can be null or empty)之类的评论似乎是一种在Design by Contract内以人类语言实施 Javadoc 的方式。

iContract使用Javadoc强制执行契约设计，现在已复活到JcontractS，可让您以更正式的方式指定不变量，前置条件，后置条件以人类的语言。

问题3

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

Java语言没有“按合同设计”功能，因此您可能很想使用Execption，但我同意您的意见，即您必须了解When to choose checked and unchecked exceptions。可能您可能使用未经检查的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：对！我忘记了异常，但我想看到它们被提及，特别是这个公共方法可以抛出的未经检查的'运行时'异常

@Mike Stone：

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

嗯，我确信希望每当发生影响合同的变更时，公共API文档都会更新。如果没有，那些API文档可能完全丢弃。

为了给你的想法添加食物（和@Scott Dorman一起去），我只是偶然发现了the future of java7 annotations

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

这样一来，如果API中有'@CheckForNull'，那么该函数的编写者可能会忘记记录它！如果语义发生变化，其API将反映出这种变化（例如“不再是@CheckForNull”）

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

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

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

5 个答案: