RFR: Updated section on Code Conventions.

[mark.reinhold at oracle.com]

For context, here is the message from me to which Magnus replied.

- Mark

----

From: mark.reinhold at oracle.com
To: jesper.wilhelmsson at oracle.com
Cc: Andreas Lundblad <github.com+5994243+aioobe at openjdk.java.net>,
 guide-dev at openjdk.java.net
Subject: Re: RFR: Updated section on Code Conventions.
Date: Thu 2020/06/25 16:51:30 -0700

2020/6/22 10:42:46 -0700, jesper.wilhelmsson at oracle.com:
>> On 22 Jun 2020, at 18:40, mark.reinhold at oracle.com wrote:
>> 
>> 2020/6/18 6:10:21 -0700, Andreas Lundblad <github.com+5994243+aioobe at openjdk.java.net>:
>>> Pull request for adding code conventions.
>> 
>> Thanks for contributing this material, but I don’t think that the
>> Developers’ Guide is the right place for it.
>> 
>> If we have agreed policies about coding style then we should treat
>> them as authoritative, normative information.  As such, they’d be
>> out of place in a Guide that’s meant only to contain tutorials and
>> suggestions.
> 
> I guess there are two ways to look at it - either these are coding
> style guidelines, or they are authoritative coding style rules. My
> impression was the former, that they were guidelines, and as such I
> think the Guide is the right place for them. If these are to be
> treated as authoritative rules however I agree, the Guide is not the
> place for them. In that case we should make sure these are published
> in the right place asap and just have the Guide link to them.

For better or for worse, code style is often a topic of much -- and
sometimes heated -- debate.  No matter what we say about these documents
merely being suggestive guidelines, at least some people will treat them
as normative and authoritative, and use them as the basis for arguing
one way or another.

The Developers’ Guide is meant to be a living document, written by its
contributors to help others more easily contribute to the JDK.  As such
it can change at any time.  Changes to it are, moreover, not broadly
reviewed, so it does not necessarily represent a consensus of JDK
contributors.

An authoritative document, by contrast, should be fairly stable, and
changes to it should be subject to broad review so that it represents a
rough consensus of JDK contributors rather than that of a smaller group
of Guide contributors.

A Java style guide published in the OpenJDK Community will also be used
by people in the broader ecosystem who will never contribute to the JDK,
but who’ve been asking us for years for an updated style guide for use
in their own work.  We should therefore try to take extra care with it.

So, I don’t think code style guidelines belong in the Developer’s Guide,
even if they are just “guidelines.”

> What would be the right place to put coding style rules?

Good question!

Fortunately we already have an established means of building consensus
around authoritative documents, namely the JEP process.  I suggest that
code style guides be published as informational JEPs, alongside existing
prominent JEPs such as those for the release process, incubator modules,
and so forth.

The JEP process and the infrastructure it rests on (JBS) aren’t perfect.
Maintaining long documents in JBS issues, in particular, is painful, and
the JBS Markdown renderer is bonkers.  With a little hacking, however, I
think we can arrange for better revision control and rendering of select
JEPs.

- Mark