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

[Joe Darcy]

Hi Darryl,

It is certainly fair to raise the point that our official code 
conventions and javadoc style are long (really long!) out of date and in 
need to revising / rewriting to capture current recommended practices.

I concede these documents should be revised, but I won't promise a 
time-line for doing so ;-)

-Joe

On 12/18/2013 01:40 PM, Darryl Mocek wrote:
> 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 
>>
>