8323158: HotSpot Style Guide should specify more include ordering

[stefank]

The HotSpot Style Guide has a section about source files and includes. The style used for includes have mostly been introduced by scripts when includeDB was replaced, but also when various other enhancements to our includes were made. Some of the introduced styles were never written down in the style guide.

I propose a couple of changes to the HotSpot Style Guide to reflect some of these implicit styles that we have. While updating the text I also took the liberty to order the items in an order that I felt was good.

Note that JDK-8323158 contains a few more suggestions, but I've only addressed the items that I think can be accepted without much contention. Either I extract the items that have not been address into a new RFE, or I create a new RFE for this PR.

There a some small whitespace tweaks that I made so that the .md and .html had a similar layout.

---

Progress

• Change must be properly reviewed (1 review required, with at least 1 Reviewer)
• Change must not contain extraneous whitespace
• Commit message must refer to an issue

Issue

• JDK-8323158: HotSpot Style Guide should specify more include ordering (Enhancement - P4)

Reviewers

• Vladimir Kozlov (@vnkozlov - Reviewer) Review applies to 51913afa
• Kim Barrett (@kimbarrett - Reviewer)
• Thomas Stuefe (@tstuefe - Reviewer)
• David Holmes (@dholmes-ora - Reviewer)

Reviewing

Using git

Checkout this PR locally:
$ git fetch https://git.openjdk.org/jdk.git pull/23388/head:pull/23388
$ git checkout pull/23388

Update a local copy of the PR:
$ git checkout pull/23388
$ git pull https://git.openjdk.org/jdk.git pull/23388/head

Using Skara CLI tools

Checkout this PR locally:
$ git pr checkout 23388

View PR using the GUI difftool:
$ git pr show -t 23388

Using diff file

Download this PR as a diff file:
https://git.openjdk.org/jdk/pull/23388.diff

Using Webrev

Link to Webrev Comment

[bridgekeeper]

👋 Welcome back stefank! A progress list of the required criteria for merging this PR into master will be added to the body of your pull request. There are additional pull request commands available for use with this pull request.

[openjdk]

@stefank This change now passes all automated pre-integration checks.

ℹ️ This project also has non-automated pre-integration requirements. Please see the file CONTRIBUTING.md for details.

After integration, the commit message for the final commit will be:

8323158: HotSpot Style Guide should specify more include ordering

Reviewed-by: kbarrett, stuefe, dholmes, kvn

You can use pull request commands such as /summary, /contributor and /issue to adjust it as needed.

At the time when this comment was updated there had been 92 new commits pushed to the master branch:

• 1079147: 8348570: CTW: Expose the code hidden by uncommon traps
• 1a74ee6: 8349092: File.getFreeSpace violates specification if quotas are in effect (win)
• 0181030: 8349006: File.getCanonicalPath should remove "(on UNIX platforms)" from its specification
• ed8945a: 8347377: Add validation checks for ICC_Profile header fields
• 1ab1c1d: 8349058: 'internal proprietary API' warnings make javac warnings unusable
• eb84702: 8349513: Remove unused BUILD_JDK_JTREG_LIBRARIES_JDK_LIBS_libTracePinnedThreads
• f12d2de: 8345212: Since checker should better handle non numeric values
• 5ec1aae: 8347842: ThreadPoolExecutor specification discusses RuntimePermission
• 3fbae32: 8349465: [UBSAN] test_os_reserve_between.cpp reported applying non-zero offset to null pointer
• e0487c7: 8346777: Add missing const declarations and rename variables
• ... and 82 more: https://git.openjdk.org/jdk/compare/1858dc141041dbea7167007b17d03fe41378c0be...master

As there are no conflicts, your changes will automatically be rebased on top of these commits when integrating. If you prefer to avoid this automatic rebasing, please check the documentation for the /integrate command for further details.

➡️ To integrate this PR with the above commit message to the master branch, type /integrate in a new comment.

[openjdk]

@stefank The following labels will be automatically applied to this pull request:

• build
• hotspot

When this pull request is ready to be reviewed, an "RFR" email will be sent to the corresponding mailing lists. If you would like to change these labels, use the /label pull request command.

[mlbridge]

Webrevs

• 01: Full - Incremental (f01c564c)
• 00: Full (51913afa)

[vnkozlov]

Looks reasonable.

[kimbarrett]

Just a couple of minor wording nits. Otherwise looks good to me.

[dougxc]

A lot of these rules looks like they could be checked with some simple scripting or additions to jcheck. Have you considered that?

[stefank]

A lot of these rules looks like they could be checked with some simple scripting or additions to jcheck. Have you considered that?

I haven't felt the urge to write such a script, but I know that others have scripts to sort the includes.

[dougxc]

I haven't felt the urge to write such a script, but I know that others have scripts to sort the includes

Ok, it was just a suggestion. My experience is that while clearly written conventions/rules are important, the more they can be automated, the less hassle for everyone.

[stefank]

I haven't felt the urge to write such a script, but I know that others have scripts to sort the includes

Ok, it was just a suggestion. My experience is that while clearly written conventions/rules are important, the more they can be automated, the less hassle for everyone.

I agree, that a script is beneficial. Do you know of anyone that would be willing to help out and write such script?

[tstuefe]

This looks good to me. Thank you.

[dholmes-ora]

Generally seems fine. Thanks.

[dholmes-ora]

What is the order for the conditional sections? Alphabetic on the include guard?

[stefank]

I don't think there's a set order. I wouldn't mind making it alphabetic with platforms includes coming before the other conditional includes.

[stefank]

FWIW, I also tend to sort the forward declarations but that's also not something that everyone does.

[tstuefe]

FWIW, I also tend to sort the forward declarations but that's also not something that everyone does.

I, too, am an obsessive sorter. Clean code is good code.

[jdksjolen]

@dougxc,

We could use clang-format for these specific include rules.

For example, when we still had precompiled.hpp I had this in my .clang-format file:

IncludeCategories: # precompiled.hpp ALWAYS first
  - Regex: 'precompiled.hpp'
    Priority: 0
    SortPriority: 0

Implementing all of the rules for Clang format is left as an exercise to the reader, and the author would be very appreciative if someone posted their solution here :-).