Should wrappers compare as equal using the == operator when they wrap the same object?

Question

I'm writing a wrapper for XML elements that allows a developer to easily parse attributes from the XML. The wrapper has no state other than the object being wrapped.

I am considering the following implementation (simplified for this example) which includes an overload for the == operator.

class XmlWrapper
{
    protected readonly XElement _element;

    public XmlWrapper(XElement element)
    {
        _element = element;
    }

    public string NameAttribute
    {
        get
        {
            //Get the value of the name attribute
        }
        set
        {
            //Set the value of the name attribute
        }
    }

    public override bool Equals(object other)
    {
        var o = other as XmlWrapper;
        if (o == null) return false;
        return _element.Equals(o._element);
    }

    public override int GetHashCode()
    {
        return _element.GetHashCode();
    }

    static public bool operator == (XmlWrapper lhs, XmlWrapper rhs)
    {
        if (ReferenceEquals(lhs, null) && ReferenceEquals(rhs, null)) return true;
        if (ReferenceEquals(lhs, null) || ReferenceEquals(rhs, null)) return false;

        return lhs._element == rhs._element;
    }

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

As I understand idiomatic c#, the == operator is for reference equality while the Equals() method is for value equality. But in this case, the "value" is just a reference to the object being wrapped. So I am not clear what is conventional or idiomatic for c#.

For example, in this code...

var underlyingElement = new XElement("Foo");
var a = new XmlWrapper(underlyingElement);
var b = new XmlWrapper(underlyingElement);

a.NameAttribute = "Hello";
b.NameAttribute = "World";

if (a == b)
{
    Console.WriteLine("The wrappers a and b are the same.");
}

....should the program output "The wrappers a and b are the same" ? Or would that be odd, i.e. violate the principal of least astonishment?

Answer 1

Since the reference to the wrapped XElement is immutable, there is no externally observable difference between two instances of XmlWrapper that wrap the same element, so it makes sense to overload == to reflect this fact.

Client code almost always cares about logical equality (which, by default, is implemented using reference equality for reference types). The fact that there are two instances on the heap is an implementation detail that clients shouldn't care about (and those that do will use Object.ReferenceEquals directly).

Answer 2

If you think it makes the most sense

The question and answer is a matter of developer expectation, this is not a technical requirement.

IF you consider a wrapper to not have an identity and have it be defined purely by its contents, then the answer to your question is yes.

But this is a recurring problem. Should two wrappers exhibit equality when they wrap different objects but with both objects having the exact same contents?

The answer repeats itself. IF the content objects have no personal identity and instead are purely defined by their content, then the content objects are effectively wrappers which will exhibit equality. If you then wrap the content objects in another wrapper, that (additional) wrapper should then also exhibit equality.

It's turtles all the way down.

---

General tip

Whenever you deviate from default behavior, it should be explicitly documented. As a developer, I expect that two reference types will not exhibit equality even if their contents are equal. If you change that behavior, I would suggest you clearly document it so that all developers are aware of this atypical behavior.

---

As I understand idiomatic c#, the == operator is for reference equality while the Equals() method is for value equality.

That is its default behavior, but this is not an immovable rule. It's a matter of convention, but conventions can be changed where justifiable.

string is a great example here, as == is also a value equality check (even when there is no string interning!). Why? Simply put: because having strings behave like value objects feels more intuitive to most developers.

If your codebase (or your developers' lives) can be notably simplified by having your wrappers exhibit value equality across the board, go for it (but document it).

If you never require reference equality checks (or they are rendered useless by your business domain), then there's no point to keeping a reference equality check around. It's better to then replace it with a value equality check so as to prevent developer error.
However, do realize that should you need reference equality checks later down the line, reimplementing it may take a notable effort.

Answer 3

You are basically comparing strings so I would be astonished if two wrappers containing the same XML content would not be considered equal, be it checked using Equals or ==.

The idiomatic rule may make sense for reference type objects in general but strings are special in an idiomatic sense, you are supposed to treat and regard them as values although technically they are reference types.

Your Wrapper postfix adds confusion though. It basically says "not an XML element". So should I treat it as a reference type after all? Semantically this would not make sense. I would be less confused if the class were named XmlContent. This would signal we care about content, not technical implementation details.