From 649ef77951d420512e385ee3c792ced80276a30a Mon Sep 17 00:00:00 2001
From: Stefan Karlsson <stefank@openjdk.org>
Date: Thu, 6 Mar 2025 07:42:16 +0000
Subject: [PATCH] 8323158: HotSpot Style Guide should specify more include
 ordering

Reviewed-by: kbarrett, stuefe, dholmes, kvn
---
 doc/hotspot-style.html | 28 ++++++++++++++++++----------
 doc/hotspot-style.md   | 29 +++++++++++++++++++++--------
 2 files changed, 39 insertions(+), 18 deletions(-)

diff --git a/doc/hotspot-style.html b/doc/hotspot-style.html
index 9f26fc66362..72e5ce66e19 100644
--- a/doc/hotspot-style.html
+++ b/doc/hotspot-style.html
@@ -207,23 +207,31 @@ the simple "getter".</p></li>
 <ul>
 <li><p>All source files must have a globally unique basename. The build
 system depends on this uniqueness.</p></li>
+<li><p>Keep the include lines within a section alphabetically sorted.</p></li>
+<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>
+<li><p>Put system includes in a section after the HotSpot include lines with a blank
+line separating the two sections.</p></li>
 <li><p>Do not put non-trivial function implementations in .hpp files. If
-the implementation depends on other .hpp files, put it in a .cpp or a
-.inline.hpp file.</p></li>
+the implementation depends on other .hpp files, put it in a .cpp or
+a .inline.hpp file.</p></li>
 <li><p>.inline.hpp files should only be included in .cpp or .inline.hpp
 files.</p></li>
-<li><p>All .inline.hpp files should include their corresponding .hpp
-file as the first include line. Declarations needed by other files
-should be put in the .hpp file, and not in the .inline.hpp file. This
-rule exists to resolve problems with circular dependencies between
-.inline.hpp files.</p></li>
+<li><p>All .inline.hpp files should include their corresponding .hpp file as
+the first include line with a blank line separating it from the rest of the
+include lines. Declarations needed by other files should be put in the .hpp
+file, and not in the .inline.hpp file. This rule exists to resolve problems
+with circular dependencies between .inline.hpp files.</p></li>
+<li><p>Do not include a .hpp file if the corresponding .inline.hpp file is included.</p></li>
+<li><p>Use include guards for .hpp and .inline.hpp files. The name of the defined
+guard should be derived from the full search path of the file relative to the
+hotspot source directory. The guard should be all upper case with all paths
+separators and periods replaced by underscores.</p></li>
 <li><p>Some build configurations use precompiled headers to speed up the
 build times. The precompiled headers are included in the precompiled.hpp
 file. Note that precompiled.hpp is just a build time optimization, so
 don't rely on it to resolve include problems.</p></li>
-<li><p>Keep the include lines alphabetically sorted.</p></li>
-<li><p>Put conditional inclusions (<code>#if ...</code>) at the end of
-the include list.</p></li>
 </ul>
 <h3 id="jtreg-tests">JTReg Tests</h3>
 <ul>
diff --git a/doc/hotspot-style.md b/doc/hotspot-style.md
index 01506629817..d0b1c82a3d7 100644
--- a/doc/hotspot-style.md
+++ b/doc/hotspot-style.md
@@ -135,9 +135,18 @@ change should be done with a "setter" accessor matched to the simple
 
 ### Source Files
 
-* All source files must have a globally unique basename.  The build
+* All source files must have a globally unique basename. The build
 system depends on this uniqueness.
 
+* Keep the include lines within a section alphabetically sorted.
+
+* 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.
+
+* Put system includes in a section after the HotSpot include lines with a blank
+line separating the two sections.
+
 * Do not put non-trivial function implementations in .hpp files. If
 the implementation depends on other .hpp files, put it in a .cpp or
 a .inline.hpp file.
@@ -146,19 +155,23 @@ a .inline.hpp file.
 files.
 
 * All .inline.hpp files should include their corresponding .hpp file as
-the first include line. Declarations needed by other files should be put
-in the .hpp file, and not in the .inline.hpp file. This rule exists to
-resolve problems with circular dependencies between .inline.hpp files.
+the first include line with a blank line separating it from the rest of the
+include lines. Declarations needed by other files should be put in the .hpp
+file, and not in the .inline.hpp file. This rule exists to resolve problems
+with circular dependencies between .inline.hpp files.
+
+* Do not include a .hpp file if the corresponding .inline.hpp file is included.
+
+* Use include guards for .hpp and .inline.hpp files. The name of the defined
+guard should be derived from the full search path of the file relative to the
+hotspot source directory. The guard should be all upper case with all paths
+separators and periods replaced by underscores.
 
 * Some build configurations use precompiled headers to speed up the
 build times. The precompiled headers are included in the precompiled.hpp
 file. Note that precompiled.hpp is just a build time optimization, so
 don't rely on it to resolve include problems.
 
-* Keep the include lines alphabetically sorted.
-
-* Put conditional inclusions (`#if ...`) at the end of the include list.
-
 ### JTReg Tests
 
 * JTReg tests should have meaningful names.