Page History

Methods should always try to return a value that allows the developer to learn about the current state of the object and/or the result of an operation. This is consistent with the advice in guideline EXP00-J. Do not ignore values returned by methods. The returned value should be as representative of the last known state as possible and should be chosen keeping in mind the perceptions and mental model of the developer.

...

Sometimes a state testing method \[[Bloch 2008|AA. Bibliography#Bloch 08]\] can be used to ensure that the object is in consistent state at all points in time. This approach is not useful in the absence of external synchronization. Also,There thereis isalso a TOCTOU race condition between invocation of the object's state testing method and the call to a method that depends on the object's state. During this interval, the object's state could change surreptitiously.

A method should not return a value or error code that does not accurately specify the object state. Clients should be able to rely on the value for performing critical decisions.

Noncompliant

...

Code Example

As shown in this example, noncompliant methods can silently corrupt the state of the object if they do not return a value that the developer can intuitively interpret.

public void updateNode(int id, int newValue){		
  Node current = root;
  while(current != null){
    if(current.getId() == id){
      current.setValue(newValue);
      break;
    }
    current = current.next;
  }
}

Compliant

...

Solution

This compliant solution returns the result of the operation; true for success and false for failure.

public boolean updateNode(int id, int newValue){		
  Node current = root;
  while(current != null){
    if(current.getId() == id){
      current.setValue(newValue);
      return true; // Node successfully updated
    }
    current = current.next;
  }
  return false;
}

Compliant

...

Solution

This compliant solution returns the updated Node so that the developer can simply check for a null value lest the operation fails. Return values for methods can vary depending on the control flow or the information that the developer finds more useful.

public Node updateNode(int id, int newValue){	
  Node current = root;
  while(current != null){
    if(current.getId() == id){
      current.setValue(newValue);
      return current;
    }
    current = current.next;
  }
  return null;
}

Compliant

...

Solution

This solution combines the best of both worlds - exceptions and status codes. In this case, an exception is thrown if the operation is not successful. This ensures that the client has to handle the event wherein the Node is not found. If the Node is found, it is updated and returned.

...