如何记录Java副作用 [英] How to Document Java Side Effects

问题描述

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

Is there a standard or best practice for writing javadocs for Java/JVM language methods which contain side effects?

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

I have a void method defined, which modifies one of the method parameters, but do not know how to document the actual return value (since there is no actual 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批注并不能真正指示正在发生的事情.

It just seems that there is no good way to tag the side effects on the object, since the @param and @return annotations do not really dictate what is going on.

推荐答案

没有用于描述副作用的标准Javadoc注释.在该方法的人类可读描述中通常会提到副作用.在您的情况下，将修改作为参数传递的对象，因此您可以考虑在@param标记之后短暂地重复副作用.

There is no standard Javadoc annotation to describe side effects. Side effects are typically mentioned in the human-readable description of the method. In your case, the object which is passed as a parameter is modified, so you can consider briefly repeating the side effect after the @param tag.

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

In any case, the @return tag is not the correct place to document side effects: your method has void as return type, so it does not return anything.

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

In your case, your Javadoc could look like:

/**
 * 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副作用的文章就介绍到这了，希望我们推荐的答案对大家有所帮助，也希望大家多多支持IT屋！