RFR: Updated section on Code Conventions.
stuart.marks at oracle.com
Wed Jul 1 05:23:08 UTC 2020
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"
Thanks for mentioning this, Joe. To this I'd add Jim Laskey's document,
Programmer's Guide To Text Blocks
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.
More information about the jdk-dev