首页
学习
活动
专区
工具
TVP
发布
社区首页 >问答首页 >api文档和“价值限制”:它们匹配吗?

api文档和“价值限制”:它们匹配吗?
EN

Stack Overflow用户
提问于 2019-03-26 00:18:11
回答 2查看 0关注 0票数 0

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

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

“值限制”,我的意思是:

  • 参数是否可以支持空值(或空字符串,或......)?
  • '返回值'可以为null或保证永远不为空(或者可以为“空”,或者......)?

样本:

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

代码语言:javascript
复制
/**
 * 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);

希望看到的是:

代码语言:javascript
复制
/**
 * 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,它们是否属于同一类?

EN

回答 2

Stack Overflow用户

发布于 2019-03-26 08:48:13

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

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

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

票数 0
EN

Stack Overflow用户

发布于 2019-03-26 10:13:07

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

很难记住总能做到这一点,但这对你班级的用户来说是件好事。如果方法呈现更改的合同(如空值被更改为不允许),那么维护它也很困难...当您更改方法的语义时,您还必须努力更新文档。

票数 0
EN
页面原文内容由Stack Overflow提供。腾讯云小微IT领域专用引擎提供翻译支持
原文链接:

https://stackoverflow.com/questions/-100001044

复制
相关文章

相似问题

领券
问题归档专栏文章快讯文章归档关键词归档开发者手册归档开发者手册 Section 归档