关于不可知的语言：api文档和“值限制”：它们匹配吗？

您经常在API文档中(例如在"公共函数的javadoc"中)看到"值限制"的描述以及经典文档吗？

注意：我不是在谈论代码中的注释

所谓"价值限制"，是指：

• 参数可以支持空值(或空字符串，或...)吗？
• "返回值"是否可以为null或保证永远不会为null(或者可以为"空"，或...)？

样品：

我经常看到的(无法访问源代码)是：

我想看到的是：

我的观点是：

当我在其中使用带有getReaderNames()函数的库时，我通常甚至不需要阅读API文档就可以猜测它的作用。但是我需要确定如何使用它。

当我要使用此功能时，我唯一需要关注的是：就参数和返回值而言，我应该期待什么？这就是我安全设置参数和安全测试返回值所需的全部知识，但是我几乎从来没有在API文档中看到过此类信息...

编辑：

这会影响是否使用已检查或未检查的异常。

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

我认为它们可以在一起，但不一定必须在一起。在您的方案中，将限制记录在生成的API文档和智能中(如果语言/ IDE支持)似乎是有意义的。

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

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

问题1

Do you often see in API documentation (as in 'javadoc of public functions' for example) the description of"value limits" as well as the classic documentation?

几乎从不。

问题2

My only concern when I want to use this function is: what should I expect in term of parameters and return values ? That is all I need to know to safely setup my parameters and safely test the return value, yet I almost never see that kind of information in API documentation...

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

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

iContract使用Javadoc来执行按合同设计，现在被复活为JcontractS，与人类语言相比，它可以以更形式化的方式指定不变式，前提条件，后置条件。

问题3

This can influence the usage or not for checked or unchecked exceptions.
What do you think ? value limits and API, do they belong together or not ?

Java语言没有按合同设计的功能，因此您可能会倾向于使用Execption，但我同意您必须知道何时选择检查和未检查异常的事实。可能您可能使用了未经检查的IllegalArgumentException，IllegalStateException，或者可能使用了单元测试，但是主要的问题是如何与其他程序员交流这种代码与按合同设计有关，并且在更改之前也应被视为合同。轻轻。

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

很难记住总是这样做，但这对您的班级用户来说是一件好事。如果方法的约定出现变化(例如，将空值更改为不允许)，也很难维护它。当您更改方法的语义时，还必须勤奋地更新文档。

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

@迈克·斯通：

you have to be diligent also to update the docs when you change the semantics of the method.

嗯，我当然希望，只要发生影响功能约定的更改，就至少要更新公共API文档。如果没有，这些API文档可能会完全删除。

为了使您的想法更加有趣(并使用@Scott Dorman)，我偶然发现了Java7注释的未来

那是什么意思？某些"边界条件"(而不是文档中的内容)应该更好地存在于API本身中，并在编译时自动与适当的"断言"生成的代码一起使用。

这样，如果API中有一个'@CheckForNull'，该函数的编写者可能甚至不编写文档就逃脱了！而且，如果语义发生变化，其API将反映该变化(例如，"不再有@CheckForNull")

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

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

我认为它们确实如此，并且始终将注释放在标头文件(c ++)中。

除了有效的输入/输出/返回注释之外，我还注意到该函数很可能引发哪些异常(由于我经常想将返回值用于...很好地返回一个值，所以我更喜欢异常而不是错误代码)