是否有针对包含副作用的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批注实际上并不能决定发生了什么。
没有标准的Javadoc注释来描述副作用。在该方法的人类可读描述中通常会提到副作用。在您的情况下，将修改作为参数传递的对象，因此您可以考虑在@param标签后短暂重复副作用。
无论如何，@return标记不是记录副作用的正确位置：您的方法具有voidas返回类型，因此它不返回任何内容。
在您的情况下，您的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";
}
}
本文收集自互联网，转载请注明来源。
如有侵权，请联系[email protected] 删除。
我来说两句