What is "Best Practice" For Comparing Two Instances of a Reference Type?

Solution 1:

Implementing equality in .NET correctly, efficiently and without code duplication is hard. Specifically, for reference types with value semantics (i.e. immutable types that treat equvialence as equality), you should implement the System.IEquatable<T> interface, and you should implement all the different operations (Equals, GetHashCode and ==, !=).

As an example, here’s a class implementing value equality:

class Point : IEquatable<Point> {
    public int X { get; }
    public int Y { get; }

    public Point(int x = 0, int y = 0) { X = x; Y = y; }

    public bool Equals(Point other) {
        if (other is null) return false;
        return X.Equals(other.X) && Y.Equals(other.Y);
    }

    public override bool Equals(object obj) => Equals(obj as Point);

    public static bool operator ==(Point lhs, Point rhs) => object.Equals(lhs, rhs);

    public static bool operator !=(Point lhs, Point rhs) => ! (lhs == rhs);

    public override int GetHashCode() => X.GetHashCode() ^ Y.GetHashCode();
}

The only movable parts in the above code are the bolded parts: the second line in Equals(Point other) and the GetHashCode() method. The other code should remain unchanged.

For reference classes that do not represent immutable values, do not implement the operators == and !=. Instead, use their default meaning, which is to compare object identity.

The code intentionally equates even objects of a derived class type. Often, this might not be desirable because equality between the base class and derived classes is not well-defined. Unfortunately, .NET and the coding guidelines are not very clear here. The code that Resharper creates, posted in another answer, is susceptible to undesired behaviour in such cases because Equals(object x) and Equals(SecurableResourcePermission x) will treat this case differently.

In order to change this behaviour, an additional type check has to be inserted in the strongly-typed Equals method above:

public bool Equals(Point other) {
    if (other is null) return false;
    if (other.GetType() != GetType()) return false;
    return X.Equals(other.X) && Y.Equals(other.Y);
}

Solution 2:

It looks like you're coding in C#, which has a method called Equals that your class should implement, should you want to compare two objects using some other metric than "are these two pointers (because object handles are just that, pointers) to the same memory address?".

I grabbed some sample code from here:

class TwoDPoint : System.Object
{
    public readonly int x, y;

    public TwoDPoint(int x, int y)  //constructor
    {
        this.x = x;
        this.y = y;
    }

    public override bool Equals(System.Object obj)
    {
        // If parameter is null return false.
        if (obj == null)
        {
            return false;
        }

        // If parameter cannot be cast to Point return false.
        TwoDPoint p = obj as TwoDPoint;
        if ((System.Object)p == null)
        {
            return false;
        }

        // Return true if the fields match:
        return (x == p.x) && (y == p.y);
    }

    public bool Equals(TwoDPoint p)
    {
        // If parameter is null return false:
        if ((object)p == null)
        {
            return false;
        }

        // Return true if the fields match:
        return (x == p.x) && (y == p.y);
    }

    public override int GetHashCode()
    {
        return x ^ y;
    }
}

Java has very similar mechanisms. The equals() method is part of the Object class, and your class overloads it if you want this type of functionality.

The reason overloading '==' can be a bad idea for objects is that, usually, you still want to be able to do the "are these the same pointer" comparisons. These are usually relied upon for, for instance, inserting an element into a list where no duplicates are allowed, and some of your framework stuff may not work if this operator is overloaded in a non-standard way.

Solution 3:

Below I have summed up what you need to do when implementing IEquatable and provided the justification from the various MSDN documentation pages.

Summary

When testing for value equality is desired (such as when using objects in collections) you should implement the IEquatable interface, override Object.Equals, and GetHashCode for your class.
When testing for reference equality is desired you should use operator==,operator!= and Object.ReferenceEquals.
You should only override operator== and operator!= for ValueTypes and immutable reference types.

Justification

IEquatable

The System.IEquatable interface is used to compare two instances of an object for equality. The objects are compared based on the logic implemented in the class. The comparison results in a boolean value indicating if the objects are different. This is in contrast to the System.IComparable interface, which return an integer indicating how the object values are different.

The IEquatable interface declares two methods that must be overridden. The Equals method contains the implementation to perform the actual comparison and return true if the object values are equal, or false if they are not. The GetHashCode method should return a unique hash value that may be used to uniquely identify identical objects that contain different values. The type of hashing algorithm used is implementation-specific.

IEquatable.Equals Method

You should implement IEquatable for your objects to handle the possibility that they will be stored in an array or generic collection.

If you implement IEquatable you should also override the base class implementations of Object.Equals(Object) and GetHashCode so that their behavior is consistent with that of the IEquatable.Equals method

Guidelines for Overriding Equals() and Operator == (C# Programming Guide)

x.Equals(x) returns true.

x.Equals(y) returns the same value as y.Equals(x)

if (x.Equals(y) && y.Equals(z)) returns true, then x.Equals(z) returns true.

Successive invocations of x. Equals (y) return the same value as long as the objects referenced by x and y are not modified.

x. Equals (null) returns false (for non-nullable value types only. For more information, see Nullable Types (C# Programming Guide).)

The new implementation of Equals should not throw exceptions.

It is recommended that any class that overrides Equals also override Object.GetHashCode.

Is is recommended that in addition to implementing Equals(object), any class also implement Equals(type) for their own type, to enhance performance.

By default, the operator == tests for reference equality by determining whether two references indicate the same object. Therefore, reference types do not have to implement operator == in order to gain this functionality. When a type is immutable, that is, the data that is contained in the instance cannot be changed, overloading operator == to compare value equality instead of reference equality can be useful because, as immutable objects, they can be considered the same as long as they have the same value. It is not a good idea to override operator == in non-immutable types.

Overloaded operator == implementations should not throw exceptions.

Any type that overloads operator == should also overload operator !=.

== Operator (C# Reference)

For predefined value types, the equality operator (==) returns true if the values of its operands are equal, false otherwise.

For reference types other than string, == returns true if its two operands refer to the same object.

For the string type, == compares the values of the strings.

When testing for null using == comparisons within your operator== overrides, make sure you use the base object class operator. If you don't, infinite recursion will occur resulting in a stackoverflow.

Object.Equals Method (Object)

If your programming language supports operator overloading and if you choose to overload the equality operator for a given type, that type must override the Equals method. Such implementations of the Equals method must return the same results as the equality operator

The following guidelines are for implementing a value type:

Consider overriding Equals to gain increased performance over that provided by the default implementation of Equals on ValueType.

If you override Equals and the language supports operator overloading, you must overload the equality operator for your value type.

The following guidelines are for implementing a reference type:

Consider overriding Equals on a reference type if the semantics of the type are based on the fact that the type represents some value(s).

Most reference types must not overload the equality operator, even if they override Equals. However, if you are implementing a reference type that is intended to have value semantics, such as a complex number type, you must override the equality operator.

Additional Gotchas

When overriding GetHashCode() make sure you test reference types for NULL before using them in the hash code.
I ran into a problem with interface-based programming and operator overloading described here: Operator Overloading with Interface-Based Programming in C#

Solution 4:

That article just recommends against overriding the equality operator (for reference types), not against overriding Equals. You should override Equals within your object (reference or value) if equality checks will mean something more than reference checks. If you want an interface, you can also implement IEquatable (used by generic collections). If you do implement IEquatable, however, you should also override equals, as the IEquatable remarks section states:

If you implement IEquatable<T>, you should also override the base class implementations of Object.Equals(Object) and GetHashCode so that their behavior is consistent with that of the IEquatable<T>.Equals method. If you do override Object.Equals(Object), your overridden implementation is also called in calls to the static Equals(System.Object, System.Object) method on your class. This ensures that all invocations of the Equals method return consistent results.

In regards to whether you should implement Equals and/or the equality operator:

From Implementing the Equals Method

Most reference types should not overload the equality operator, even if they override Equals.

From Guidelines for Implementing Equals and the Equality Operator (==)

Override the Equals method whenever you implement the equality operator (==), and make them do the same thing.

This only says that you need to override Equals whenever you implement the equality operator. It does not say that you need to override the equality operator when you override Equals.