RFR: Updated section on Code Conventions.

[mark.reinhold at oracle.com]

2020/6/30 22:23:08 -0700, stuart.marks at oracle.com:
> ...
> 
> I will quibble here with Brian's intimation that these documents are not 
> authoritative. I would argue that being "from the source" implies that the 
> documents *are* authoritative. They were written by people very close to the 
> development of the features themselves, and as such are in the best position to 
> give informed advice about proper and improper use, avoidance of pitfalls, 
> recommended practices, and so forth.

Agreed.

> With this in mind, I will state that I do not think the Java Style Guide belongs 
> in the Developer's Guide. The reason is that the documents have fundamentally 
> different editorial stances.
> 
> The Developer's Guide is primarily operational: it contains information about 
> how to do things, where to look, whom to ask, step by step procedures to follow, 
> tips & tricks for working effectively, and so forth. It covers a wide range of 
> topic areas. For example, one tip might be
> 
>      To switch branches, use 'git switch' instead of 'git checkout -b'.
> 
> Git experts might reasonably take issue with this advice. However, git experts 
> might not have any opinion at all on other topics, such as one that covers the 
> proper usage of the noreg-long label on a JBS issue. As such, the Developer's 
> Guide benefits from input from many individuals with a broad range of interests, 
> each contributing bits of expertise in different areas.
> 
> 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.

Agreed.  Strongly.

This brings up a related, and important, question: If we’re going to have
an authoritative style guide with a uniform editorial voice, then who
will sign up to be the editor?

Andreas’s draft may be a reasonable starting point, but since he hasn’t
been an active OpenJDK contributor for some years now I don’t imagine
that he can commit to such a role.

Not only would we need an editor to spend time on this, and maintain it
for the long haul, but it would inevitably require some of the limited
time of at least some of our most experienced contributors.  Is that the
best use of their time?

> 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.

Indeed, that would be most unwise.

Fortunately, it’s not difficult to address this problem.  The job that
publishes https://openjdk.java.net/jeps could easily pull the text of
select JEPs from any repo that we want, rather than use the bodies of
the corresponding JBS issues.  We could repurpose the existing jep/jeps
repo for that purpose, or (more likely) just set up a new one on GitHub.

- Mark