如何记录 Java 副作用

Question

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

我定义了一个 void 方法，它修改了一个方法参数，但不知道如何记录实际的 return 值（因为没有实际的 return）。

/**
  * @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 注释并没有真正说明发生了什么。

Answer 1

没有标准的 Javadoc 注释来描述副作用。副作用通常在该方法的人类可读描述中提及。在你的例子中，作为参数传递的对象被修改了，所以你可以考虑在 @param 标签之后简单地重复副作用。

无论如何，@return 标记不是记录副作用的正确位置：您的方法具有 void 作为 return 类型，因此它不会 return 任何事物。

在您的情况下，您的 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";
   }
}

如何记录 Java 副作用

How to Document Java Side Effects

javadoc

side-effects