Proposed source code and regression test suite improvement projects for JDK 9

[Darryl Mocek]

We should also update the pertinent information on the official Oracle 
pages so others working on OpenJDK can have a reference.  For example, 
this page on Javadoc style: 
http://www.oracle.com/technetwork/java/javase/documentation/index-137868.html#styleguide 
still recommends using <code></code> as the way to comment keywords and 
names in Javadocs.  There's also the "Code Conventions for the Java 
Programming Language" 
(http://www.oracle.com/technetwork/java/codeconv-138413.html) which was 
last revised and updated on April 20, 1999 (The PDF is dated 1997).  
This should be updated to support modern programming practices as well 
as new Java features.  As the web page states: "Code conventions improve 
the readability of the software, allowing engineers to understand new 
code more quickly and thoroughly.".

Darryl

On 12/13/2013 11:13 AM, Joe Darcy wrote:
> Hello,
>
> With JDK 9 about to get underway, I'd like to propose several source 
> code and regression test suite improvement efforts to tackle during 
> this release.
>
> Over the years, the JDK code base has accumulated a bit of technical 
> debt in various areas. In JDK 8, efforts have already been underway to 
> pay down that technical debt including:
>
> * doclint cleanup: core libs is now doclint-clean and over 1,000 of 
> the doclint warnings in client libs have been fixed [1]
>
> * javac lint cleanup: many lint issues have been resolved [2] and a 
> number of lint categories are configured to cause fatal errors if they 
> are found when building the jdk repo [3]
>
> * test stabilization: numerous regression tests in the jdk repo failed 
> intermittently, ran for an unnecessarily long time, or suffered from 
> other flaws that have been corrected [4]
>
> For JDK 9, I propose we complete these initiatives for the code in the 
> langtools and jdk repositories (then possibly extend to jaxp, jaxws, 
> etc.):
>
> * Source code in java.* and javax.* is doclint clean for public and 
> protected elements and the docs build is configured to fail on a 
> doclint issue. The generated javadoc is also tidy clean.
>
> * Java sources compile cleanly under "javac -Xlint:all -Werror" and 
> the build is configured to fail if a lint issue is introduced.
>
> * There are no chronic intermittently failing tests and clean jdk test 
> runs are a common occurrence.
>
> Reducing C/C++ build warnings would be a worthwhile goal too, but is 
> complicated by the number of C/C++ compilers used across different 
> supported platforms. In addition, various structural properties of 
> javadoc should be regularized ({@code Foo} instead of 
> <code>Foo</code>, package-info.java instead of package.html, @throws 
> instead of @exception, etc.) and the Java source code should use 
> contemporary coding idioms (lambda, diamond, etc.).
>
> There are thousands of lint and doclint issues remaining, but they can 
> largely be addressed in parallel without interfering with each other, 
> as was seen in JDK 8. While some effort will be required to get these 
> issues addressed initially, once the source code and tests are in a 
> clean state, we would benefit from tooling support to prevent certain 
> classes of errors from being introduced.
>
> Comments?
>
> Thanks,
>
> -Joe
>
> [1] 
> https://bugs.openjdk.java.net/issues/?jql=project%20%3D%20jdk%20and%20fixVersion%20%3D%208%20and%20resolution%20%3D%20Fixed%20and%20labels%20%3D%20doclint
>
> [2] 
> https://bugs.openjdk.java.net/issues/?jql=project%20%3D%20jdk%20and%20fixVersion%20%3D%208%20and%20resolution%20%3D%20Fixed%20and%20labels%20in%20(lint%2C%20fixit)
>
> [3] JDK-8024643 Turn on javac lint checking in building the jdk repo
> https://bugs.openjdk.java.net/browse/JDK-8024643
>
> JDK-8024603 Turn on javac lint checking for auxiliaryclass, empty, and 
> try in jdk build
> https://bugs.openjdk.java.net/browse/JDK-8024603
>
> [4] 
> https://bugs.openjdk.java.net/issues/?jql=project%20%3D%20jdk%20and%20fixVersion%20%3D%208%20and%20resolution%20%3D%20Fixed%20and%20labels%20%3D%20teststabilization 
>