When should a method of a class return the same instance after modifying itself?

Question

I have a class that has three methods A(), B() and C(). Those methods modify the own instance.

While the methods have to return an instance when the instance is a separate copy (just as Clone()), I got a free choice to return void or the same instance (return this;) when modifying the same instance in the method and not returning any other value.

When deciding for returning the same modified instance, I can do neat method chains like obj.A().B().C();.

Would this be the only reason for doing so?

Is it even okay to modify the own instance and return it, too? Or should it only return a copy and leave the original object as before? Because when returning the same modified instance the user would maybe assume the returned value is a copy, otherwise it would not be returned? If it's okay, what's the best way to clarify such things on the method?

Answer 1

When to use chaining

Function chaining is mostly popular with languages where an IDE with auto-complete is common place. For example, almost all C# developers use Visual Studio. Therefore, if you're developing with C# adding chaining to your methods can be a time saver for users of that class because Visual Studio will assist you in building the chain.

On the other hand, languages like PHP that are highly dynamic in nature and often don't have auto-complete support in IDEs will see fewer classes that support chaining. Chaining will only be appropriate when correct phpDocs are employed to expose the chainable methods.

What is chaining?

Given a class named Foo the following two methods are both chainable.

function what() { return this; }
function when() { return new Foo(this); }

The fact that one is a reference to the current instance, and one creates a new instance doesn't change that these are chainable methods.

There is no gold rule that a chainable method must only reference the current object. Infact, chainable methods can be across two different classes. For example;

class B { function When() { return true; } };
class A { function What() { return new B(); } };

var a = new A();
var x = a.What().When();

There is no reference to this in any of the above example. The code a.What().When() is an example of a chaining. What's interesting is that the class type B is never assigned to a variable.

A method is chained when it's return value becomes used as the next component of an expression.

Here are some more example

 // return value never assigned.
 myFile.Open("something.txt").Write("stuff").Close();

// two chains used in expression
int x = a.X().Y() * b.X().Y();

// a chain that creates new strings
string name = str.Substring(1,10).Trim().ToUpperCase();

When to use this and new(this)

Strings in most languages are immutable. So chaining method calls always results in new strings being created. Where as an object like StringBuilder can be modified.

Consistency is best practice.

If you have methods that modify the state of an object and return this, then don't mix in methods that return new instances. Instead, create a specific method called Clone() that will do this explicitly.

 var x  = a.Foo().Boo().Clone().Foo();

That is a lot clearer as to what is going on inside a.

The Step Outside And Back Trick

I call this the step out and back trick, because it solves a lot of common problems related to chaining. It basically means that you step out of the original class into a new temporary class and then back to the original class.

The temporary class exists only to provide special features to the original class, but only under special conditions.

There are often times when a chain needs to change state, but class A can not represent all of those possible states. So during a chain a new class is introduced that contains a reference back to A. This allows the programmer to step into a state and back to A.

Here is my example, let the special state be known as B.

class A {
    function Foo() { return this; }
    function Boo() { return this; }
    function Change() return new B(this); }
}

class B {
    var _a;
    function (A) { _a = A; }
    function What() { return this; }
    function When() { return this; }
    function End() { return _a; }
}

var a = new A();
a.Foo().Change().What().When().End().Boo();

Now that is a very simple example. If you wanted to have more control, then B could return to a new super-type of A that has different methods.

Answer 2

Those methods modify the own instance.

Depending on the language, having methods that return void/unit and modify their instance or parameters is non-idiomatic. Even in languages that used to do that more (C#, C++), it is going out of fashion with the shift towards more functional style programming (immutable objects, pure functions). But let's assume there's a good reason for now.

Would this be the only reason for doing so?

For certain behaviors (think x++) it is expected that the operation returns the result, even though it modifies the variable. But that's largely the only reason to do it on your own.

Is it even okay to modify the own instance and return it, too? Or should it only return a copy and leave the original object as before? Because when return the same modified instance the user would maybe admit the returned value is a copy, otherwise it would not be returned? If it's okay, what's the best way to clarify such things on the method?

It depends.

In languages where copy/new and return is common (C# LINQ and strings) then returning the same reference would be confusing. In languages where modify and return is common (some C++ libraries) then copying would be confusing.

Making the signature unambiguous (by returning void or using language constructs like properties) would be the best way to clarify. After that, making the name clear like SetFoo to show that you're modifying the existing instance is good. But the key is to maintain the idioms of the language/library you're working with.

Answer 3

(I assumed C++ as your programming-language)

For me this is mostly a readability aspect. If A, B, C are modifiers, especially if this is a temporary object passed as a parameter to some function, e.g.

do_something(
      CPerson('name').age(24).height(160).weight(70)
      );

compared to

{
   CPerson person('name');
   person.set_age(24);
   person.set_height(160);
   person.set_weight(70);
   do_something(person);
}

Regrading if it's ok to return a reference to the modified instance, I'd say yes, and point you for example to the stream operators '>>' and '<<' (http://www.cprogramming.com/tutorial/operator_overloading.html)

Answer 4

You could also do the method chaining thing with copy return rather than modify return.

A good C# example is string.Replace(a,b) which doesn't change the string on which it was invoked but instead returns a new string allowing you to chain merrily away.