equals(), hashCode() & Identity

Two kinds of "equal"

When you compare two objects, you have to decide which question you're asking:

• Reference / identity equality — are these two variables pointing at the very same object in memory? In Java this is p1 == p2; in Python it's p1 is p2. It compares addresses, not contents, so two separately created objects are never identity-equal even if every field matches.
• Value equality — do these two objects hold the same contents? This is p1.equals(p2) in Java, p1 == p2 in Python, p1 == p2 (operator overload) in C++. By default, most languages make value equality fall back to identity — so until you override it, equals just checks == and reports false for two distinct objects.

That default is the trap. You create Point(2, 3) twice, you mean them to be the same point, but the language compares addresses and says they're different.

Overriding equals to compare by value

To make two equal-looking objects actually count as equal, you override the equality method to compare the fields you care about instead of the memory address:

@Override
public boolean equals(Object o) {
    if (this == o) return true;            // same object → trivially equal
    if (!(o instanceof Point p)) return false;
    return this.x == p.x && this.y == p.y; // compare by VALUE
}

Why hashCode must agree with equals

Hash-based collections like HashSet and HashMap don't scan every element to find a match — that would be slow. Instead they call hashCode() to compute a number, use it to pick a bucket, and only compare objects within that bucket using equals(). So a lookup is really two steps: which bucket? (hashCode), then is it really here? (equals).

That two-step dance only works if hashCode and equals agree. If two objects are equals-equal but land in different buckets because their hash codes differ, the collection looks in the wrong bucket, never finds the match, and treats them as different. That's why the contract demands they move together.

The equals / hashCode contract

A correct equals must satisfy four properties, and hashCode must stay consistent with it:

• Reflexive — x.equals(x) is always true. An object equals itself.
• Symmetric — if x.equals(y) is true, then y.equals(x) must be true too. Equality can't depend on which side you start from.
• Transitive — if x.equals(y) and y.equals(z), then x.equals(z) must hold. Equality chains together.
• Consistent — repeated calls return the same answer as long as the objects don't change. No random results.
• Equal ⇒ equal hash — if x.equals(y), then x.hashCode() == y.hashCode(). This is the rule that keeps hash collections working.
• *Unequal may collide — the reverse is not required: two unequal objects are allowed to share a hashCode. That's a normal collision*, and equals resolves it inside the bucket. Good hash functions just keep collisions rare.

What breaks in HashSet / HashMap

Concretely, with equals overridden but hashCode left as the default (identity-based), here's the failure: you add p1 = Point(2,3), then add p2 = Point(2,3). They're equals-equal, so the set should keep just one. But their default hash codes differ, so they hash to different buckets; the set never compares them with equals, and you end up with two 'equal' points in a set that's supposed to hold no duplicates. Later, set.contains(new Point(2,3)) may return false even though the point is clearly in there — it's looking in the wrong bucket.

How each language spells it

• Java — override boolean equals(Object) and int hashCode() together. Objects.equals(...) and Objects.hash(...) make this easy and null-safe.
• Python — define __eq__(self, other) for value equality and __hash__(self) for hashing. Note: defining __eq__ without __hash__ makes the class unhashable (Python sets __hash__ = None), so you can't put it in a set or use it as a dict key until you add __hash__.
• C++ — overload operator== for value equality, and specialize std::hash<Point> so the type can be a key in std::unordered_set / std::unordered_map.
• JavaScript — there is only reference equality (=== / == compare object references). There's no equals/hashCode hook and Set/Map key on reference identity, so for value equality you must compare fields manually (or key your Map by a serialized string like `${x},${y}`).

When to override equals & hashCode

Override them whenever your class is a value type — an object that's defined by what it holds, not which instance it is. Money, coordinates, a date, an ID wrapper, a colour: two of these with identical fields are the same thing, and you'll want to compare them by value, deduplicate them in a Set, or use them as Map/dict keys. The moment a type ends up as a key or inside a hash-based collection, correct equals and hashCode are mandatory.