RFR: Updated section on Code Conventions.

mark.reinhold at oracle.com mark.reinhold at oracle.com
Thu Jul 2 00:11:46 UTC 2020

2020/6/29 2:21:21 -0700, Andrew Haley <aph at redhat.com>:
> On 26/06/2020 15:13, Magnus Ihse Bursie wrote:
>> ...
>> On 2020-06-22 18:40, mark.reinhold at oracle.com wrote:
>>> 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.
>> I do not agree that this is a valid argument. We can't claim that we
>> should not publish guidelines, since some people will not understand
>> what "guidelines" mean. If you are serious about this argument, then
>> we can just as well shut down the entire Developer's Guide, since
>> it's all about non-authoritative suggestions.
> Mark's point, and I hope I'm not misrepresenting him, is that figuring
> out what the coding style should be, without being over-prescriptive,
> is difficult and requires a JEP. Putting non-authoritative Java style
> guidelines in the Developers’ Guide risks bypassing any review
> process.


More precisely, it risks bypassing any meaningful review beyond the small
number of people who maintain the Developers’ Guide.  No matter how well
intentioned those people might be, such an important document should be
more stable, and changes to it more tightly controlled, than the
Developers’ Guide is meant to be.

(One way to address that is to make every OpenJDK contributor also be a
 Developers’ Guide maintainer, but that doesn’t scale very well.  Many
 contributors will be interested in changes to code-style guidelines.
 Few, I suspect, will care to review every other change to the Guide.)

>> And even if we do think it is desirable, for every year we wait
>> until we publish a guide, the harder it will become to create a new,
>> globally recognized, normative style guide.
> True, but a nonexistent style guide is far better than one which in
> effect constrains developers and reviewers in such a way as to make
> working on the JDK worse, in terms of both the experience for the
> developer and the outcome.


- Mark

More information about the jdk-dev mailing list