RFR: Updated section on Code Conventions.

[Stuart Marks]

On 6/26/20 6:37 PM, Joe Darcy wrote:
> On 6/26/2020 10:54 AM, Brian Goetz wrote:
>> To the extent that it forms a “from the source” set of recommendations for new 
>> language features (which are coming fast and furious these days!), a 
>> non-authoritative guide still has significant value.
> 
> As a concrete example, such a style guide would provide a natural and more 
> discoverable home for useful documents like Stuart's
> 
>      "Local Variable Type Inference: Style Guidelines"
>      https://openjdk.java.net/projects/amber/LVTIstyle.html

Thanks for mentioning this, Joe. To this I'd add Jim Laskey's document,

	Programmer's Guide To Text Blocks
	https://cr.openjdk.java.net/~jlaskey/Strings/TextBlocksGuide_v9.html

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.

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.

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.

s'marks