RFR: Updated section on Code Conventions.

[Kim Barrett]

> On Jul 1, 2020, at 1:23 AM, Stuart Marks <stuart.marks at oracle.com> wrote:
> A style guide is fundamentally different. To be useful, it must be authoritative -- as mentioned above -- and it also must be highly cohesive. It needs to have a uniform editorial voice that is adhered to consistently throughout the document. For example, it might take a prescriptive vs. a descriptive stance, or it might choose a vocabulary for recommendations of varying strength ("can", "should", "must", etc.) and use that throughout the document. As such, a style guide is not at all amenable to a "crowdsourcing" approach and must be edited by a handful of individuals. Since the editorial approach for the style guide material is so different from that of the Developer's Guide, it follows that the style guide should be a different document.
> 
> Personally I'm agnostic to the exact process for delivering a style guide. If Mark thinks a JEP is required, then maybe that's the best way forward. But I could imagine other paths forward that wouldn't use a JEP.
> 
> I would strongly recommend against making the style guide itself be a JEP. Today, editing a JEP with more than a page or two of text is already unwieldy. It's easy to introduce errors inadvertently, and history tracking is virtually nonexistent. It seems unwise to put JIRA+markdown plugin improvements into the critical path of delivering a style guide. Doing that might prove fatal.

As someone with another Style Guide update in the works (for HotSpot),
I agree having it *be* a JEP is not desirable.

It currently resides in the OpenJDK wiki, but that hasn't served us
well. It has been suggested that it should reside in the Developers'
Guide (by some of the same people suggesting that for the Java Style
Guide).  I think that would be okay if it can have its own rules for
updates.  The current draft proposes update rules, which are also in
the C++14 update JEP (JDK-8208089) that is driving the document
revision.  (Whether those are the right rules remains to be seen,
though nobody has objected or suggested something else in the 1.5+
years since that was added to the JEP, or in review of the new draft
document.) 

I've also discussed the possibility of putting it in the jdk/jdk
repository, probably in the toplevel doc directory.

My preference would be to put it in a repository with decent revision
control (unlike either the wiki or JBS).  Whether that's the
Dev-Guide, jdk/jdk, or some other agreeable place is, I think, of less
importance.  Having it be in the Dev-Guide (or some similar place) has
the benefit of having a web "mirror", unlike jdk/jdk/doc.