Как обрабатывать побочные эффекты Java

Question

Существует ли стандартная или лучшая практика для написания javadocs для языковых методов Java/JVM, содержащих побочные эффекты?

У меня есть метод 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 аннотаций на самом деле не диктуют, что происходят.

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