如何记录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屋!