What's wrong with returning this?

Question

At the company I work for there's a document describing good practices that we should adhere to in Java. One of them is to avoid methods that return this, like for example in:

class Properties {

  public Properties add(String k, String v) {
   //store (k,v) somewhere
     return this;
  }

}

I would have such a class so that I'm able to write:

 properties.add("name", "john").add("role","swd"). ...

I've seen such idiom many times, like in StringBuilder and don't find anything wrong with it.

Their argumentation is :

... can be the source of synchronization problems or failed expectations about the states of target objects.

I can't think of a situation where this could be true, can any of you give me an example?

EDIT The document doesn't specify anything about mutability, so I don't see the diference between chaining the calls and doing:

properties.add("name", "john");
properties.add("role", "swd");

I'll try to get in touch with the originators, but I wanted to do it with my guns loaded, thats' why I posted the question.

SOLVED: I got to talk with one of the authors, his original intention was apparently to avoid releasing objects that are not yet ready, like in a Builder pattern, and explained that if a context switch happens between calls, the object could be in an invalid state. I argued that this had nothing to do with returning this since you could make the same mistake buy calling the methods one by one and had more to do with synchronizing the building process properly. He admitted the document could be more explicit and will revise it soon. Victory is mine/ours!

Answer 1

My guess is that they are against mutable state (and often are rightly so). If you are not designing fluent interfaces returning this but rather return a new immutable instance of the object with the changed state, you can avoid synchronization problems or have no "failed expectations about the states of target objects". This might explain their requirement.

Answer 2

The only serious basis for the practice is avoiding mutable objects; the criticism that it is "confusing" and leads to "failed expectations" is quite weak. One should never use an object without first getting familiar with its semantics, and enforcing constraints on the API just to cater for those who opt out of reading Javadoc is not a good practice at all— especially because, as you note, returning this to achieve a fluent API design is one of the standard approaches in Java, and indeed a very welcome one.

Answer 3

I think sometimes this approach can be really useful, for example in 'builder' pattern.

I can say that in my organization this kind of things is controlled by Sonar rules, and we don't have such a rule.

Another guess is that maybe the project was built on top of existing codebase and this is kind of legacy restriction.

So the only thing I can suggest here is to talk to the people who wrote this doc :)

Hope this helps