How to Document Java Side Effects

Question

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

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";
   }
}

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.

Answer 1

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.

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.

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";
   }
}