Javahard

Why must `equals()` and `hashCode()` follow a contract?

Answer

If two objects are equal according to `equals()`, they must have the same `hashCode()`. Hash-based collections (HashMap/HashSet) rely on it; breaking the contract leads to “missing” entries and hard-to-debug behavior.

final class User {
  private final String email;

  User(String email) {
    this.email = email;
  }

  @Override public boolean equals(Object o) {
    if (this == o) return true;
    if (!(o instanceof User)) return false;
    return email.equals(((User) o).email);
  }

  @Override public int hashCode() {
    return email.hashCode();
  }
}

Advanced answer

Deep dive

Hash-based collections work in two steps: 1) Use `hashCode()` to pick a bucket. 2) Use `equals()` to find the matching key inside that bucket.

Contract highlights:

If `a.equals(b)` is true, then `a.hashCode() == b.hashCode()` must be true.
The reverse is not required (hash collisions are allowed).
Both should be consistent over time for keys stored in maps/sets.

Practical guidance

Use immutable fields for equality keys (or never mutate them while the object is in a HashMap/HashSet).
Prefer records/value objects for stable equality.

Common pitfalls

Mutating fields used by `hashCode()` after inserting into a HashSet (entry becomes “lost”).
Overriding `equals()` but forgetting `hashCode()`.
Poor hash functions that cause many collisions (performance drops).

Answer

Advanced answer

Deep dive

Practical guidance

Common pitfalls

Related questions