您是否经常在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,它们是否属于同一类?
发布于 2019-03-26 08:48:13
我认为他们可以属于一个整体,但不一定必须属于一起。在您的场景中,似乎有意义的是,限制以这样的方式记录,即它们出现在生成的API文档和智能感知中(如果语言/ IDE支持它)。
我认为这也取决于语言。例如,Ada具有一个“受限整数”的本机数据类型,您可以在其中定义一个整数变量,并明确指出它只会(并且始终)在某个数值范围内。在这种情况下,数据类型本身表示限制。它应该仍然可以通过API文档和intellisense查看和发现,但不是开发人员必须在注释中指定的内容。
但是,像Java和C#这样的语言没有这种类型的受限整数,因此开发人员必须在注释中指定它,如果它是应该成为公共文档的一部分的信息。
发布于 2019-03-26 10:13:07
我认为那些边界条件绝对属于API。但是,我会(并经常)更进一步,并指出那些空值的含义。我指出它会抛出异常,或者我解释传递边界值时的预期结果。
很难记住总能做到这一点,但这对你班级的用户来说是件好事。如果方法呈现更改的合同(如空值被更改为不允许),那么维护它也很困难...当您更改方法的语义时,您还必须努力更新文档。
https://stackoverflow.com/questions/-100001044
复制相似问题