equals, hashCode & Object Contracts

Description

When are two objects "the same"? By default, both Java and Python say: only if they're the very same object in memory. For values - points, money, dates, ids - you usually want them compared by their contents instead, and hash-based collections (HashMap, HashSet, dict, set) depend on you doing it correctly. This skill covers the equality contract, why equals and hashCode (__eq__ and __hash__) must always change together, and the bugs that follow when they don't.

Here's the kind of bug we mean:

class Point {
    final int x, y;
    Point(int x, int y) { this.x = x; this.y = y; }
}

Set<Point> visited = new HashSet<>();
visited.add(new Point(1, 2));
visited.contains(new Point(1, 2));   // false!

class Point:
    def __init__(self, x: int, y: int):
        self.x, self.y = x, y


visited = set()
visited.add(Point(1, 2))
Point(1, 2) in visited      # False!

Two points with the same coordinates are different objects, and by default objects are compared by identity. The set can't find the point, even though it's "right there".

We'll go from simple to more technical:

1. The contract: the rules equality must follow, and the one rule linking it to hashing.
2. How hash collections use both methods, step by step.
3. Where it breaks: mutable keys, inheritance, and comparisons that disagree.

The contract

To compare by value, override equals - and whenever you override equals, you must override hashCode too (in Python, __eq__ and __hash__ - and Python enforces half of it: a class that defines __eq__ without __hash__ gets __hash__ = None and can't go in a set or be a dict key at all):

• Reflexive: a.equals(a) is true.
• Symmetric: a.equals(b) if and only if b.equals(a).
• Transitive: if a.equals(b) and b.equals(c), then a.equals(c).
• Consistent: the answer doesn't change unless the objects change.
• equals(null) is false.
• Equal objects must have equal hash codes. (Unequal objects may share a hash code.)

final class Point {
    private final int x, y;
    Point(int x, int y) { this.x = x; this.y = y; }

    @Override public boolean equals(Object o) {
        if (this == o) return true;
        if (!(o instanceof Point p)) return false;
        return x == p.x && y == p.y;
    }

    @Override public int hashCode() { return Objects.hash(x, y); }
}

class Point:
    def __init__(self, x: int, y: int):
        self._x, self._y = x, y

    def __eq__(self, other: object) -> bool:
        if not isinstance(other, Point):
            return NotImplemented              # let Python try the other side, then fall back to identity
        return (self._x, self._y) == (other._x, other._y)

    def __hash__(self) -> int:
        return hash((self._x, self._y))

# Or simply: @dataclass(frozen=True) with fields x and y

Or simply: record Point(int x, int y) {} - records generate a correct equals and hashCode from their components. (Python: @dataclass(frozen=True) generates __eq__ and __hash__ from the fields.)

How hash collections use it, step by step

1. HashMap.put(key, value) computes key.hashCode() to choose a bucket.
2. Inside that bucket it uses equals to find a matching key.
3. get(key) repeats the same two steps.
4. If equal keys had different hash codes, they'd land in different buckets and get would miss.
5. If a key's hash code changes after insertion, it's stranded in the wrong bucket forever.

Where you'll see it

• Every HashMap, HashSet, ConcurrentHashMap and caching library relies on this contract.
• String, Integer and records all implement value equality correctly.
• ORMs (JPA/Hibernate) are notorious for equality bugs on entities - usually solved by comparing on a stable business key or the id.

Which tool for which job?

Common mistakes

Check yourself

Try to answer before opening each one - recalling beats re-reading.

1. You override equals but not hashCode. What goes wrong with a HashSet?

2. Why is it dangerous to modify an object after using it as a HashMap key?

3. What's the quickest way to get a correct equals and hashCode for a small value type?

Key takeaways

• By default, equals means "same object"; override it for value equality.
• Override equals ⇒ override hashCode: equal objects must have equal hash codes.
• Never mutate a field used in hashCode while the object is inside a hash collection - prefer immutable keys.
• Keep compareTo consistent with equals; prefer final classes or records for value types.