如何记录 Java 副作用答案

【问题标题】：How to Document Java Side Effects如何记录 Java 副作用
【发布时间】：2016-07-24 17:31:14
【问题描述】：

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

我定义了一个 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 注释并不能真正指示正在发生的事情。

【问题讨论】：

这在我看来是你抽象的泄漏
我不想谈论副作用或泄漏抽象——我只想写一些 cmets 来记录遗留方法在做什么。
没有标准的 JavaDoc 注释，例如 @SideEffectTowWatchFor 或 @LeakyAbstraction（我完全承认我和几乎所有其他人都这样做了）所以只要确保你清楚有关正在发生的事情、预期内容等的文档。本质上，您的合同定义了这种方法来以这种方式影响对象。
自从我多年前开始进行 java 编程以来，javadoc 对副作用进行注释的能力一直困扰着我。如果java不允许副作用，那么为什么要有类变量？ rant>

标签： javadoc side-effects

【解决方案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";
   }
}

【讨论】：