title: Managing highly repetitive code and documentation in Java
body: <p>Highly repetitive code is generally a bad thing, and there are design patterns that can help minimize this. However, sometimes it's simply inevitable due to the constraints of the language itself. Take the following example from <code>java.util.Arrays</code>:</p>
  
  <pre><code>/**
   * Assigns the specified long value to each element of the specified
   * range of the specified array of longs.  The range to be filled
   * extends from index &lt;tt&gt;fromIndex&lt;/tt&gt;, inclusive, to index
   * &lt;tt&gt;toIndex&lt;/tt&gt;, exclusive.  (If &lt;tt&gt;fromIndex==toIndex&lt;/tt&gt;, the
   * range to be filled is empty.)
   *
   * @param a the array to be filled
   * @param fromIndex the index of the first element (inclusive) to be
   *        filled with the specified value
   * @param toIndex the index of the last element (exclusive) to be
   *        filled with the specified value
   * @param val the value to be stored in all elements of the array
   * @throws IllegalArgumentException if &lt;tt&gt;fromIndex &amp;gt; toIndex&lt;/tt&gt;
   * @throws ArrayIndexOutOfBoundsException if &lt;tt&gt;fromIndex &amp;lt; 0&lt;/tt&gt; or
   *         &lt;tt&gt;toIndex &amp;gt; a.length&lt;/tt&gt;
   */
  public static void fill(long[] a, int fromIndex, int toIndex, long val) {
      rangeCheck(a.length, fromIndex, toIndex);
      for (int i=fromIndex; i&lt;toIndex; i++)
          a[i] = val;
  }
  </code></pre>
  
  <p>The above snippet appears in the source code 8 times, with very little variation in the documentation/method signature but <em>exactly the same method body</em>, one for each of the root array types <code>int[]</code>, <code>short[]</code>, <code>char[]</code>, <code>byte[]</code>, <code>boolean[]</code>, <code>double[]</code>, <code>float[]</code>, and <code>Object[]</code>.</p>
  
  <p>I believe that unless one resorts to reflection (which is an entirely different subject in itself), this repetition is inevitable. I understand that as a utility class, such high concentration of repetitive Java code is highly atypical, but even with the best practice, <strong>repetition does happen</strong>! Refactoring doesn't always work because it's not always possible (the obvious case is when the repetition is in the documentation).</p>
  
  <p>Obviously maintaining this source code is a nightmare. A slight typo in the documentation, or a minor bug in the implementation, is multiplied by however many repetitions was made. In fact, the best example happens to involve this exact class:</p>
  
  <p><a href="http://googleresearch.blogspot.com/2006/06/extra-extra-read-all-about-it-nearly.html" rel="noreferrer">Google Research Blog - Extra, Extra - Read All About It: Nearly All Binary Searches and Mergesorts are Broken (by Joshua Bloch, Software Engineer)</a></p>
  
  <p>The bug is a surprisingly subtle one, occurring in what many thought to be just a simple and straightforward algorithm.</p>
  
  <pre><code>    // int mid =(low + high) / 2; // the bug
      int mid = (low + high) &gt;&gt;&gt; 1; // the fix
  </code></pre>
  
  <p>The above line <strong>appears 11 times in the source code</strong>!</p>
  
  <p>So my questions are:</p>
  
  <ul>
  <li>How are these kinds of repetitive Java code/documentation handled in practice? How are they developed, maintained, and tested?
  
  <ul>
  <li>Do you start with "the original", and make it as mature as possible, and then copy and paste as necessary and hope you didn't make a mistake?</li>
  <li>And if you did make a mistake in the original, then just fix it everywhere, unless you're comfortable with deleting the copies and repeating the whole replication process?</li>
  <li>And you apply this same process for the testing code as well?</li>
  </ul></li>
  <li>Would Java benefit from some sort of limited-use source code preprocessing for this kind of thing?
  
  <ul>
  <li>Perhaps Sun has their own preprocessor to help write, maintain, document and test these kind of repetitive library code?</li>
  </ul></li>
  </ul>
  
  <hr>
  
  <p>A comment requested another example, so I pulled this one from Google Collections: <a href="http://code.google.com/p/google-collections/source/browse/trunk/src/com/google/common/base/Predicates.java" rel="noreferrer">com.google.common.base.Predicates</a> lines 276-310 (<code>AndPredicate</code>) vs lines 312-346 (<code>OrPredicate</code>).</p>
  
  <p>The source for these two classes are identical, except for:</p>
  
  <ul>
  <li><code>AndPredicate</code> vs <code>OrPredicate</code> (each appears 5 times in its class)</li>
  <li><code>"And("</code> vs <code>Or("</code> (in the respective <code>toString()</code> methods)</li>
  <li><code>#and</code> vs <code>#or</code> (in the <code>@see</code> Javadoc comments)</li>
  <li><code>true</code> vs <code>false</code> (in <code>apply</code>; <code>!</code> can be rewritten out of the expression)</li>
  <li><code>-1 /* all bits on */</code> vs <code>0 /* all bits off */</code> in <code>hashCode()</code></li>
  <li><code>&amp;=</code> vs <code>|=</code> in <code>hashCode()</code></li>
  </ul>