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

Question

I came across this recently, up until now I have been happily overriding the equality operator (==) and/or Equals method in order to see if two references types actually contained the same data (i.e. two different instances that look the same).

I have been using this even more since I have been getting more in to automated testing (comparing reference/expected data against that returned).

While looking over some of the coding standards guidelines in MSDN I came across an article that advises against it. Now I understand why the article is saying this (because they are not the same instance) but it does not answer the question:

1. What is the best way to compare two reference types?
2. Should we implement IComparable? (I have also seen mention that this should be reserved for value types only).
3. Is there some interface I don't know about?
4. Should we just roll our own?!

Many Thanks ^_^

Update

Looks like I had mis-read some of the documentation (it's been a long day) and overriding Equals may be the way to go..

If you are implementing reference types, you should consider overriding the Equals method on a reference type if your type looks like a base type such as a Point, String, BigNumber, and so on. Most reference types should 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 should override the equality operator.

Answer 1

For complex objects that will yield specific comparisons then implementing IComparable and defining the comparison in the Compare methods is a good implementation.

For example we have "Vehicle" objects where the only difference may be the registration number and we use this to compare to ensure that the expected value returned in testing is the one we want.

Answer 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.

Answer 3

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.

Answer 4

I tend to use what Resharper automatically makes. for example, it autocreated this for one of my reference types:

 public override bool Equals(object obj)
 {
  if (ReferenceEquals(null, obj)) return false;
  if (ReferenceEquals(this, obj)) return true;
  return obj.GetType() == typeof (SecurableResourcePermission) && Equals((SecurableResourcePermission) obj);
 }

 public bool Equals(SecurableResourcePermission obj)
 {
  if (ReferenceEquals(null, obj)) return false;
  if (ReferenceEquals(this, obj)) return true;
  return obj.ResourceUid == ResourceUid && Equals(obj.ActionCode, ActionCode) && Equals(obj.AllowDeny, AllowDeny);
 }

 public override int GetHashCode()
 {
  unchecked
  {
   int result = (int) ResourceUid;
   result = (result*397) ^ (ActionCode != null ? ActionCode.GetHashCode() : 0);
   result = (result*397) ^ AllowDeny.GetHashCode();
   return result;
  }
 }

If you want to override == and still do ref checks, you can still use Object.ReferenceEquals.

Answer 5

Implementing equality in .NET correctly and efficiently is really hard. For instance, you should implement System.IEquatable<T> and should implement all the different operations in a consistent and efficient manner without code duplication. Even following the guidelines, I've found that incredibly hard to remember, therefore I've created a few snippets for C# and VB to fill in all the boilerplate code. The actual comparison logic then has to be adjusted in just one place. Unfortunately, classes and structures require different handling.

As an example, the following class after inserting the snippet:

class Point {
    #region Implementation of equality

    public bool Equals(Point other) {
        if (object.ReferenceEquals(other, null)) return false;
        // TODO Implement comparison logic here. E.g.:
        // return X.Equals(other.X) && Y.Equals(other.Y);
        throw new Exception("The method or operation is not implemented.");
    }

    public override bool Equals(object obj) {
        return Equals(obj as Point);
    }

    public static bool operator ==(Point lhs, Point rhs) {
        return
            object.ReferenceEquals(lhs, rhs) ||
            !object.ReferenceEquals(lhs, null) && lhs.Equals(rhs);
    }

    public static bool operator !=(Point lhs, Point rhs) {
        return !(lhs == rhs);
    }

    public override int GetHashCode() {
        // TODO Implement comparison logic here. E.g.:
        // return X.GetHashCode() ^ Y.GetHashCode();
        throw new Exception("The method or operation is not implemented.");
    }

    #endregion
}

The snippets are available for download. To use them, type cequals<tab> (for classes) or sequals<tab> for structs inside the class/struct code. The download is an unsigned VSI community component installer package. If you don't trust the content, simply change the file extension to .zip and open/copy the files contained within manually.

Important!

This code intentionally (!) tries to equate 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 below, 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, an additional type check has to be inserted in the strongly-typed Equals method above:

public bool Equals(Point other) {
    if (object.ReferenceEquals(other, null)) return false;
    if (other.GetType() != GetType()) return false;
    // TODO Implement comparison logic here. E.g.:
    // return X.Equals(other.X) && Y.Equals(other.Y);
    throw new Exception("The method or operation is not implemented.");
}

Answer 6

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: http://stackoverflow.com/questions/728434/operator-overloading-with-interface-based-programming-in-c