8323158: HotSpot Style Guide should specify more include ordering by stefank · Pull Request #23388 · openjdk/jdk

stefank · 2025-01-31T13:56:58Z

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 · 2025-01-31T13:57:50Z

👋 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 · 2025-01-31T13:59:01Z

@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 276 new commits pushed to the master branch:

b17c0b6: 8350585: InlineSecondarySupersTest must be guarded on ppc64 by COMPILER2
62f39bd: 8350636: Potential null-pointer dereference in MallocSiteTable::new_entry
cfeb7d6: 8350497: os::create_thread unify init thread attributes part across UNIX platforms
8cfebc4: 8350571: Remove mention of Tonga test suite from JMX tests
c413549: 8349860: Make Class.isArray(), Class.isInterface() and Class.isPrimitive() non-native
a9c9f7f: 8192647: GClocker induced GCs can starve threads requiring memory leading to OOME
aa70f0a: 8347348: Clarify that the HTTP server in jdk.httpserver module is not a full featured server
d551dac: 8350103: Test containers/systemd/SystemdMemoryAwarenessTest.java fails on Linux ppc64le SLES15 SP6
ab86a13: 8350548: java.lang.classfile package javadoc has errors
e1081cf: 8348536: Remove remain SIZE_FORMAT usage after JDK-8347990
... and 266 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 · 2025-01-31T13:59:43Z

@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 · 2025-01-31T14:03:24Z

Webrevs

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

vnkozlov

Looks reasonable.

kimbarrett

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

doc/hotspot-style.md

dougxc · 2025-02-01T07:19:02Z

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

stefank · 2025-02-03T12:11:35Z

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 · 2025-02-03T12:14:53Z

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 · 2025-02-04T12:31:06Z

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 · 2025-02-05T01:42:36Z

doc/hotspot-style.html

+<li><p>Put conditional inclusions (`#if ...`) at the end of the section of HotSpot
+include lines. This also applies to macro-expanded includes of platform
+dependent files.</p></li>


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

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.

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

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.

johan-sjolen · 2025-02-05T12:39:52Z

@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 :-).

magicus · 2025-02-25T15:11:04Z

/label -build

openjdk · 2025-02-25T15:12:39Z

@magicus
The build label was successfully removed.

stefank · 2025-03-06T07:41:00Z

This RFR has now been out for a while, with positive feedback from HotSpot Members, and no negative feedback. I think that this we have reached consensus about this update.

Thanks for reviewing!

/integrate

openjdk · 2025-03-06T07:42:17Z

Going to push as commit 649ef77.
Since your change was applied there have been 408 commits pushed to the master branch:

5c552a9: 8349358: [JMH] Cannot access class jdk.internal.vm.ContinuationScope
e82031e: 8350756: C2 SuperWord Multiversioning: remove useless slow loop when the fast loop disappears
3626ac3: 8204868: java/util/zip/ZipFile/TestCleaner.java still fails with "cleaner failed to clean zipfile."
4bb3d81: 8351138: Running subset of gtests gets error printing result information
107ee87: 8346954: [JMH] jdk.incubator.vector.MaskedLogicOpts fails due to IndexOutOfBoundsException
11a37c8: 8351165: Remove unused includes from vmStructs
c3b4819: 8351074: Disallow null prefix and suffix in DecimalFormat
6012e8d: 8350808: Small typos in JShell method SnippetEvent.toString()
661bd5b: 8343478: Remove unnecessary @SuppressWarnings annotations (core-libs)
61d9ab9: 8350854: Include thread counts in safepoint logging
... and 398 more: https://git.openjdk.org/jdk/compare/1858dc141041dbea7167007b17d03fe41378c0be...master

Your commit was automatically rebased without conflicts.

openjdk · 2025-03-06T07:42:23Z

@stefank Pushed as commit 649ef77.

💡 You may see a message that your pull request was closed with unmerged commits. This can be safely ignored.

8323158: HotSpot Style Guide should specify more include ordering

51913af

openjdk bot added the rfr Pull request is ready for review label Jan 31, 2025

openjdk bot added hotspot hotspot-dev@openjdk.org build build-dev@openjdk.org labels Jan 31, 2025

vnkozlov approved these changes Jan 31, 2025

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Jan 31, 2025

kimbarrett reviewed Jan 31, 2025

View reviewed changes

doc/hotspot-style.md Outdated Show resolved Hide resolved

doc/hotspot-style.md Outdated Show resolved Hide resolved

stefank added 2 commits February 3, 2025 13:08

Update hotspot-style.html

b312f9f

Update hotspot-style.md

f01c564

openjdk bot removed the ready Pull request is ready to be integrated label Feb 3, 2025

tstuefe approved these changes Feb 4, 2025

View reviewed changes

openjdk bot added the ready Pull request is ready to be integrated label Feb 4, 2025

dholmes-ora approved these changes Feb 5, 2025

View reviewed changes

kimbarrett approved these changes Feb 6, 2025

View reviewed changes

openjdk bot removed the build build-dev@openjdk.org label Feb 25, 2025

openjdk bot added the integrated Pull request has been integrated label Mar 6, 2025

openjdk bot closed this Mar 6, 2025

openjdk bot removed ready Pull request is ready to be integrated rfr Pull request is ready for review labels Mar 6, 2025

Conversation

stefank commented Jan 31, 2025 • edited by openjdk bot Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Progress

Issue

Reviewers

Reviewing

Uh oh!

bridgekeeper bot commented Jan 31, 2025

Uh oh!

openjdk bot commented Jan 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Uh oh!

openjdk bot commented Jan 31, 2025

Uh oh!

mlbridge bot commented Jan 31, 2025 • edited Loading Uh oh! There was an error while loading. Please reload this page.

Uh oh!

Webrevs

Uh oh!

vnkozlov left a comment

Choose a reason for hiding this comment

Uh oh!

kimbarrett left a comment

Choose a reason for hiding this comment

Uh oh!

Uh oh!

Uh oh!

dougxc commented Feb 1, 2025

Uh oh!

stefank commented Feb 3, 2025

Uh oh!

dougxc commented Feb 3, 2025

Uh oh!

stefank commented Feb 4, 2025

Uh oh!

tstuefe left a comment

Choose a reason for hiding this comment

Uh oh!

dholmes-ora left a comment

Choose a reason for hiding this comment

Uh oh!

dholmes-ora Feb 5, 2025

Choose a reason for hiding this comment

Uh oh!

stefank Feb 5, 2025

Choose a reason for hiding this comment

Uh oh!

stefank Feb 5, 2025

Choose a reason for hiding this comment

Uh oh!

tstuefe Feb 5, 2025

Choose a reason for hiding this comment

Uh oh!

johan-sjolen commented Feb 5, 2025

Uh oh!

magicus commented Feb 25, 2025

Uh oh!

openjdk bot commented Feb 25, 2025

Uh oh!

stefank commented Mar 6, 2025

Uh oh!

openjdk bot commented Mar 6, 2025

Uh oh!

openjdk bot commented Mar 6, 2025

Uh oh!

Reviewers

Assignees

Labels

Milestone

Development

Uh oh!

8 participants

stefank commented Jan 31, 2025 •

edited by openjdk bot

Loading

openjdk bot commented Jan 31, 2025 •

edited

Loading

mlbridge bot commented Jan 31, 2025 •

edited

Loading