api 文档和“值限制”:他们匹配吗?
-
09-06-2019 - |
题
您是否经常在 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,它们是否属于一起?
解决方案
我觉得他们 能 属于在一起但不一定 有 属于在一起。在您的场景中,限制以出现在生成的 API 文档和智能感知中的方式记录似乎是有意义的(如果语言/IDE 支持它)。
我认为这也取决于语言。例如,Ada 的本机数据类型是“受限整数”,您可以在其中定义整数变量并明确指示它仅(且始终)位于某个数值范围内。在这种情况下,数据类型本身表明了限制。它应该仍然可以通过 API 文档和智能感知可见和发现,但开发人员不必在注释中指定。
然而,像 Java 和 C# 这样的语言没有这种类型的受限整数,因此如果它是应成为公共文档一部分的信息,则开发人员必须在注释中指定它。
其他提示
我认为这些边界条件绝对属于 API。然而,我会(而且经常)更进一步指出这些空值的含义。要么我指示它将抛出异常,要么我解释传入边界值时的预期结果是什么。
记住总是这样做是很困难的,但这对于你的班级的用户来说是一件好事。如果方法呈现的合同发生更改(例如将空值更改为不允许),那么维护它也很困难...当您更改方法的语义时,您还必须勤奋地更新文档。
问题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
, ,或者您可能会使用单元测试,但主要问题是如何与其他程序员沟通,此类代码是关于按合同设计的,并且在过于轻易地更改之前应将其视为合同。
我认为他们这样做,并且总是在头文件(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);
@火枪手:正确的!我忘记了异常,但我希望看到它们被提及,特别是此公共方法可能抛出的未经检查的“运行时”异常
@迈克·斯通:
当您更改方法的语义时,您还必须勤奋地更新文档。
嗯,我当然希望 公共API文档 至少每当发生影响函数契约的更改时都会更新。如果没有,这些 API 文档可能会被完全删除。
为了给你的想法添加食物(并与@Scott Dorman一起),我只是偶然发现 java7注解的未来
这意味着什么?某些“边界条件”,而不是在文档中,应该在 API 本身中更好,并在编译时自动使用适当的“断言”生成的代码。
这样,如果 API 中存在“@CheckForNull”,函数的编写者可能甚至不需要记录它!如果语义发生变化,其 API 将反映该变化(例如“不再使用 @CheckForNull”)
这种方法表明,“边界条件”的记录是额外的好处,而不是强制性的做法。
但是,这不包括函数返回对象的特殊值。为此,一个 完全的 仍然需要文档。