如何记录Java副作用

时间:2016-04-05 00:25:15

标签: javadoc side-effects

是否有编写包含副作用的Java / JVM语言方法的javadoc的标准或最佳实践?

我定义了一个void方法,它修改了一个方法参数,但不知道如何记录实际的返回值(因为没有实际的返回值)。

/**
  * @param obj - reference object
  * @return obj - obj.name is changed to 'hello' //TODO figure out javadoc annotation
 */
void methodName(Object obj) {
   if (obj != null) {
       obj.name = "hello";
   }
}

似乎没有好的方法来标记对象的副作用,因为@param和@return注释并没有真正决定发生了什么。

1 个答案:

答案 0 :(得分:1)

没有标准的Javadoc注释来描述副作用。在人类可读的方法描述中通常提到副作用。在您的情况下,修改了作为参数传递的对象,因此您可以考虑在@param标记之后简要重复副作用。

在任何情况下,@return标记都不是记录副作用的正确位置:您的方法具有void作为返回类型,因此它不会返回任何内容。

在您的情况下,您的Javadoc可能如下所示:

/**
 * Methods a name. This method sets the "name" attribute of obj to "hello".
 * @param obj reference object ("name" attribute is modified by this method)
 */
void methodName(Object obj) {
   if (obj != null) {
       obj.name = "hello";
   }
}