api 文档和“值限制”：它们匹配吗？
您是否经常在 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，它们是否属于一起？
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 ?
Note: I am not talking about comments within the code
By "value limits", I mean:
- does a parameter can support a null value (or an empty String, or...) ?
- does a 'return value' can be null or is guaranteed to never be null (or can be "empty", or...) ?
Sample:
What I often see (without having access to source code) is:
/**
* 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);
What I like to see would be:
/**
* 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);
My point is:
When I use a library with a getReaderNames() function in it, I often do not even need to read the API documentation to guess what it does. But I need to be sure how to use it.
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...
Edit:
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 ?
如果你对这篇内容有疑问，欢迎到本站社区发帖提问 参与讨论，获取更多帮助，或者扫码二维码加入 Web 技术交流群。
绑定邮箱获取回复消息
由于您还没有绑定你的真实邮箱，如果其他用户或者作者回复了您的评论，将不能在第一时间通知您！
发布评论
评论（5）
我认为它们可以属于在一起，但不一定必须属于在一起。 在您的场景中，限制以出现在生成的 API 文档和智能感知中的方式记录似乎是有意义的（如果语言/IDE 支持它）。
我认为这也取决于语言。 例如，Ada 的本机数据类型是“受限整数”，您可以在其中定义整数变量并明确指示它仅（且始终）位于某个数值范围内。 在这种情况下，数据类型本身表明了限制。 它应该仍然可以通过 API 文档和智能感知可见和发现，但开发人员不必在注释中指定。
然而，像 Java 和 C# 这样的语言没有这种类型的受限整数，因此如果它是应成为公共文档一部分的信息，则开发人员必须在注释中指定它。
I think they can belong together but don't necessarily have to belong together. In your scenario, it seems like it makes sense that the limits are documented in such a way that they appear in the generated API documentation and intellisense (if the language/IDE support it).
I think it does depend on the language as well. For example, Ada has a native data type that is a "restricted integer", where you define an integer variable and explicitly indicate that it will only (and always) be within a certain numeric range. In that case, the datatype itself indicates the restriction. It should still be visible and discoverable through the API documentation and intellisense, but wouldn't be something that a developer has to specify in the comments.
However, languages like Java and C# don't have this type of restricted integer, so the developer would have to specify it in the comments if it were information that should become part of the public documentation.
我认为他们这样做，并且总是在头文件（c++）中添加注释。
除了有效的输入/输出/返回注释之外，我还注意到函数可能抛出哪些异常（因为我经常想将返回值用于......以及返回一个值，所以我更喜欢异常而不是错误代码）
I think they do, and have always placed comments in the header files (c++) arcordingly.
In addition to valid input/output/return comments, I also note which exceptions are likly to be thrown by the function (since I often want to use the return value for...well returning a value, I prefer exceptions over error codes)
@火枪手：对！ 我忘记了异常，但我希望看到它们被提及，特别是这个公共方法可能抛出
@Mike Stone 的未经检查的“运行时”异常：
嗯，我确实希望每当发生影响函数契约的更改时，公共 API 文档至少得到更新。 如果没有，这些 API 文档可能会被完全删除。
为了给你的想法添加食物（并与@Scott Dorman一起），我偶然发现java7 注释的未来
这意味着什么？ 某些“边界条件”，而不是在文档中，应该在 API 本身中更好，并在编译时自动使用适当的“断言”生成的代码。
这样，如果 API 中存在“@CheckForNull”，函数的编写者可能甚至不需要记录它！ 如果语义发生变化，其 API 将反映该变化（例如“不再使用 @CheckForNull”）。
这种方法表明，对于“边界条件”，文档是一种额外的奖励，而不是强制性的做法。
但是，这不包括函数返回对象的特殊值。 为此，仍然需要完整文档。
@Fire Lancer: Right! I forgot about exception, but I would like to see them mentioned, especially the unchecked 'runtime' exception that this public method could throw
@Mike Stone:
Mmmm I sure hope that the public API documentation is at the very least updated whenever a change -- that affects the contract of the function -- takes place. If not, those API documentations could be drop altogether.
To add food to yours thoughts (and go with @Scott Dorman), I just stumble upon the future of java7 annotations
What does that means ? That certain 'boundary conditions', rather than being in the documentation, should be better off in the API itself, and automatically used, at compilation time, with appropriate 'assert' generated code.
That way, if a '@CheckForNull' is in the API, the writer of the function might get away with not even documenting it! And if the semantic change, its API will reflect that change (like 'no more @CheckForNull' for instance)
That kind of approach suggests that documentation, for 'boundary conditions', is an extra bonus rather than a mandatory practice.
However, that does not cover the special values of the return object of a function. For that, a complete documentation is still needed.
我认为这些边界条件绝对属于 API。 然而，我会（而且经常）更进一步指出这些空值的含义。 要么我指示它将抛出异常，要么我解释传入边界值时的预期结果是什么。
很难记住总是这样做，但这对于您的类的用户来说是一件好事。 如果方法提出的合同发生更改（例如将空值更改为不允许），那么维护它也很困难......当您更改方法的语义时，您还必须勤奋地更新文档。
I think those kinds of boundary conditions most definitely belong in the API. However, I would (and often do) go a step further and indicate WHAT those null values mean. Either I indicate it will throw an exception, or I explain what the expected results are when the boundary value is passed in.
It's hard to remember to always do this, but it's a good thing for users of your class. It's also difficult to maintain it if the contract the method presents changes (like null values are changed to no be allowed)... you have to be diligent also to update the docs when you change the semantics of the method.
问题1
几乎从不。
问题2
如果我不正确地使用函数，我会期望一个
RuntimeException< /code> 由该方法抛出，或者在程序的另一个（有时很远）部分中抛出RuntimeException。像
@param aReaderNameRegexp 过滤器这样的注释......（可以为空或空）在我看来是一种实现按契约设计，在 Javadoc。iContract使用 Javadoc 来强制按契约进行设计，现在又重新出现在JcontractS，它允许您以比人类语言更正式的方式指定不变量、前置条件、后置条件。问题3
Java 语言没有“按契约设计”功能，因此您可能会想使用
Execption，但我同意您的观点，即您必须了解 何时选择检查和非检查异常。 也许您可能会使用未经检查的IllegalArgumentException、IllegalStateException，或者您可能会使用单元测试，但主要问题是如何与其他程序员沟通此类代码是关于按合同设计的，并且在轻易改变之前应将其视为合同。Question 1
Almost never.
Question 2
If I used a function not properly I would expect a
RuntimeExceptionthrown by the method or aRuntimeExceptionin another (sometimes very far) part of the program.Comments like
@param aReaderNameRegexp filter in order to ... (can be null or empty)seems to me a way to implement Design by Contract in a human-being language inside Javadoc.Using Javadoc to enforce Design by Contract was used by
iContract, now resurrected intoJcontractS, that let you specify invariants, preconditions, postconditions, in more formalized way compared to the human-being language.Question 3
Java language doesn't have a Design by Contract feature, so you might be tempted to use
Execptionbut I agree with you about the fact that you have to be aware about When to choose checked and unchecked exceptions. Probably you might use uncheckedIllegalArgumentException,IllegalStateException, or you might use unit testing, but the major problem is how to communicate to other programmers that such code is about Design By Contract and should be considered as a contract before changing it too lightly.