equals, hashCode, and the contract between them

The default equals (inherited from Object) compares references — a.equals(b) is true only when a and b are the exact same object. For a value type, that is almost never what you want.

public final class Point {
    private final int x, y;

    public 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 other)) return false;
        return x == other.x && y == other.y;
    }
}

This alone already breaks something. HashSet, HashMap, and every hash-based collection use hashCode() to decide where to look before they ever call equals(), and they only call equals on an entry whose hash code matches. Point above still has Object's identity hashCode, so two equal points almost always get different hash codes, equals is never consulted, and a HashSet<Point> ends up holding both.

Try it

The contract

Java's actual rule, from Object's documentation: if two objects are equal according to equals, they must return the same hashCode. The reverse is not required — unequal objects may share a hash code, which is just a collision, and every hash-based collection already handles collisions.

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

Objects.hash(...) combines any number of fields into one hash code correctly, which is why hand-rolling one is rarely worth it. The two methods must be overridden together, and hashCode may only read fields that equals also compares. A hashCode that reads a field equals ignores breaks the contract as surely as leaving it out. The reverse is legal: a hashCode built from fewer fields than equals only produces more collisions — even return 0; satisfies the contract, it just turns every hash lookup into a linear scan.

Why the immutability matters

If a field used in hashCode changes after the object is inside a HashSet or used as a HashMap key, its entry does not move — the object is still filed under its old hash code, and a lookup computed from its current state looks in the wrong place and does not find it.

This is the practical reason a key type should be immutable: correctness inside a hash-based collection depends on the hash code never changing while the object is a member of one.

A Java record generates a correct equals, hashCode, and toString for you, over exactly its declared fields, which is why a plain value type is usually better written as a record than as a hand rolled class.

Common mistakes

• Writing public boolean equals(Point other). That is an overload, not an override: collections call equals(Object), which is still Object's identity check. Annotating it with @Override turns the mistake into a compile error, which is the reason to always write the annotation.
• Overriding equals and not hashCode (the first example): set and map lookups silently disagree with equals.
• Mutating a field that hashCode reads while the object is a key (the second example): contains returns false for an object that is visibly in the set.
• Building hashCode from a field that equals does not compare, or from a raw representation when compares a normalised one — the exercise below is exactly that trap.

What interviewers ask

• What happens if you override equals but not hashCode? Equal objects get different hash codes, so HashSet keeps duplicates and HashMap.get with an equal key returns null.
• Can two unequal objects have the same hash code? Yes — that is a collision; it costs performance, never correctness. Only equal objects are required to share one.
• Why should a HashMap key be immutable? The entry is filed by the hash code at insertion time; if the key's state changes, lookups compute a different hash and miss it.
• instanceof or getClass() in equals? getClass() never lets a subclass instance equal a parent instance; instanceof does, which is only safe when subclasses cannot change what equality means — one reason value classes are usually final or records.