title: Is overloading equals worthwhile
body: <p>Consider the following snippet:</p>
  
  <pre><code>import java.util.*;
  public class EqualsOverload {
      public static void main(String[] args) {
          class Thing {
              final int x;
              Thing(int x)          { this.x = x; }
              public int hashCode() { return x; }
  
              public boolean equals(Thing other) { return this.x == other.x; }
          }
          List&lt;Thing&gt; myThings = Arrays.asList(new Thing(42));
          System.out.println(myThings.contains(new Thing(42))); // prints "false"
      }
  }
  </code></pre>
  
  <p>Note that <code>contains</code> returns <code>false</code>!!! We seems to have lost our things!!</p>
  
  <p>The bug, of course, is the fact that we've accidentally <em>overloaded</em>, instead of <em>overridden</em>, <a href="http://java.sun.com/javase/6/docs/api/java/lang/Object.html#equals%28java.lang.Object%29" rel="noreferrer"><code>Object.equals(Object)</code></a>. If we had written <code>class Thing</code> as follows instead, then <code>contains</code> returns <code>true</code> as expected.</p>
  
  <pre><code>        class Thing {
              final int x;
              Thing(int x)          { this.x = x; }
              public int hashCode() { return x; }
  
              @Override public boolean equals(Object o) {
                  return (o instanceof Thing) &amp;&amp; (this.x == ((Thing) o).x);
              }
          }
  </code></pre>
  
  <p><em>Effective Java 2nd Edition, Item 36: Consistently use the Override annotation</em>, uses essentially the same argument to recommend that <code>@Override</code> should be used consistently. This advice is good, of course, for if we had tried to declare <code>@Override equals(Thing other)</code> in the first snippet, our friendly little compiler would immediately point out our silly little mistake, since it's an overload, not an override.</p>
  
  <p>What the book doesn't specifically cover, however, is whether overloading <code>equals</code> is a good idea to begin with. Essentially, there are 3 situations:</p>
  
  <ul>
  <li>Overload only, no override -- <strong>ALMOST CERTAINLY WRONG</strong>!
  
  <ul>
  <li>This is essentially the first snippet above</li>
  </ul></li>
  <li>Override only (no overload) -- one way to fix
  
  <ul>
  <li>This is essentially the second snippet above</li>
  </ul></li>
  <li>Overload and override combo -- another way to fix</li>
  </ul>
  
  <p>The 3rd situation is illustrated by the following snippet:</p>
  
  <pre><code>        class Thing {
              final int x;
              Thing(int x)          { this.x = x; }
              public int hashCode() { return x; }
  
              public boolean equals(Thing other) { return this.x == other.x; }
              @Override public boolean equals(Object o) {
                  return (o instanceof Thing) &amp;&amp; (this.equals((Thing) o));
              }
          }
  </code></pre>
  
  <p>Here, even though we now have 2 <code>equals</code> method, there is still one equality logic, and it's located in the overload. The <code>@Override</code> simply delegates to the overload.</p>
  
  <p>So the questions are:</p>
  
  <ul>
  <li>What are the pros and cons of "override only" vs "overload &amp; override combo"?</li>
  <li>Is there a justification for overloading <code>equals</code>, or is this almost certainly a bad practice?</li>
  </ul>