如何在文档中提及空参数？

Question

我正在开发一种API，想知道通常提及空参数的方式：

A. 像这样写 @throw NullPointerException if P is null，假设所有文档未提到此问题的方法都将接受空参数：

/**
/* Does something...
/* @param p the paramteter to do something...
/* @throws NullPointerException if p is null
...

B. 像这个参数可以为空这样写，假设没有提到不接受空参数：

/**
/* Does something...
/* @param p the parameter... this can be null
...

在常识中，我觉得A更合理，但是一直写这个确实很痛苦。

你会选择哪种方式？

谢谢！

- Ryoichiro Oka

Answer 1

选项A更加清晰，并且具有额外的好处，即scaladoc将正确显示异常。

然而：在任何可以使用Option类型的地方，最好的实践和更符合惯用语法的做法是使用null。这实际上是任何不涉及Java代码接口的地方。这样，类型系统本身将记录参数可以省略，编译器将能够确保您永远不会忘记检查缺少的值。

- Ash Wilson

---

因此，任何可空参数都应该是“Option”，我可以假设用户会理解任何不是“Option”的参数不应该是“null”，那么我就不需要明确提及“NullPointerException”了？ - Ryoichiro Oka

没错！这就是要点。以下是一个快速介绍：http://blog.orbeon.com/2011/04/scalas-optionsomenone.html - Ash Wilson

顺便说一下，除了进行大量的“if”检查之外，还有许多方便处理“Options”的方法。例如，您可以使用模式匹配，或者（通常非常优雅地！）将它们视为一个小型集合，可以容纳零个或一个元素。 - Ash Wilson

非常有帮助！非常感谢：）） - Ryoichiro Oka

Answer 2

我认为两者都做比较好。你应该提到如果会出现NullPointerException的情况。在参数可能为空的情况下，不仅要说它可以为空，而且要描述这意味着什么。例如：

* @param locale the Locale used to format dates, or null to use the system's default Locale.

- Dawood ibn Kareem

---

@RyoichiroOka，你在这个问题上有一个“java”标签，然后把它编辑掉了吗？我回答时认为它是Java。我对Scala一无所知，如果有人评论说它不适用于Scala，我很乐意删除它。 - Dawood ibn Kareem

非常抱歉 :P 我按照你说的做了，只是完全忘记我正在使用Scala。但还是谢谢你的回答，因为我在Java中也一直在思考同样的问题 :) - Ryoichiro Oka