@@ -7,25 +7,37 @@ helpviewer_keywords: ["headers, C++ library", "libraries, Standard C++", "C++ St
 ---
 # Compare header units, modules, and precompiled headers
 
-Historically, you'd include the the standard library with a directive like `#include <vector>`. It's expensive to include header files because they are reprocessed over and over by every source file that includes them, so precompiled headers were introduced to speed compilation by translating them once and reusing the result. In C++20, modules were introduced as a significant improvement on header files and precompiled headers. Header units were introduced as a way of temporarily bridging the gap between header files and modules so that you can get some of the speed and robustness benefits of modules while you migrate your code. Then, the C++23 standard library introduced support for importing the standard library as named modules--which is the fastest and most robust way to consume the standard library.
+Historically, you'd include the standard library with a directive like `#include <vector>`. It's expensive to include header files because they're processed by every source file that includes them.
+
+Precompiled headers (PCH) were introduced to speed compilation by translating them once and reusing the result.
+
+In C++20, modules were introduced as a significant improvement on header files and precompiled headers.
+
+Header units were introduced as a way of temporarily bridging the gap between header files and modules so that you can get some of the speed and robustness benefits of modules while you migrate your code.
+
+Then, the C++23 standard library introduced support for importing the standard library as named modules--which is the fastest and most robust way to consume the standard library.
 
 To help you sort out the different options, this article compares the traditional `#include` method against precompiled headers, header units, and the `std` and `std.compat` named modules.
 
 The following table is arranged by compiler processing speed and robustness, with `#include` being the slowest and least robust, and `import` being the fastest and most robust.
 
 | Method | Summary |
 |---|---|
-| `#include` | This is the 'classic' way of doing things. Disadvantages: exposes macros and internal implementation (functions and types that start with an underscore which library implementors use to indicate it's internal and shouldn't use), is fragile (the order of #includes can modify behavior or break code and are affected by macro definitions), is slow and gets slower when the same file is included in multiple files because the header file has to be reprocessed for each file that includes it. |
+| `#include` | This is the 'classic' way of doing things. On disadvantage is that they exposes macros and internal implementation. Internal implementation is often exposed as functions and types that start with an underscore, which is a convention to indicate that it's internal and shouldn't be used. Header files are fragile because the order of #includes can modify behavior or break code and are affected by macro definitions. Header files slow compilation, particularly when the same file is included in multiple files because the header file has to be processed for each file that includes it. |
 | [Precompiled header](../build/creating-precompiled-header-files.md) | A precompiled header (PCH) improves compile time by creating a compiler memory snapshot of a set of header files. This is an improvement on rebuilding header files over and over. PCH files have restrictions that make them difficult to build and maintain. In terms of speed and robustness, PCH files are faster than `#include` but slower than `import`.|
 | [Header units](../build/walkthrough-header-units.md) | This is a new feature in C++20 that allows you to import 'well-behaved' header files as modules. Header units are faster than `#include`, and are easier, significantly smaller, and faster than pre-compiled header files (PCH). Header units are an 'in-between' step meant to help transition to named modules in cases where you rely on macros defined in header files, since named modules don't expose macros. Header units are slower than importing a named module. Header units aren't affected by macro defines unless they're specified on the command line when the header unit is built--making them more robust than header files. Header units expose the macros and internal implementation defined in them just as header file do, which named modules don't. As a rough approximation of file size, a 250-megabyte PCH file might be represented by an 80-megabyte header unit file. |
-| [Modules](modules-cpp.md) | This is the fastest and most robust way to import functionality. Support for importing modules was introduced in C++20. The C++23 standard library introduces the two named modules described in this topic. When you import `std`, you get the standard names such as `std::vector`, `std::cout`, but no extensions, no internal helpers such as `_Sort_unchecked`, and no macros. The order of imports doesn't matter because there are no macro or other side-effects. As a rough approximation of file size, a 250-megabyte PCH file might be represented by an 80-megabyte header unit file, which might be represented by a 25-megabyte module. The reason named modules are faster is because when a named module is compiled into an `.ifc` file and an `.obj` file, the compiler emits a structured representation of the source code that can be loaded quickly when the module is imported. The compiler can do some work (like name resolution) before emitting the `.ifc` file because of how named modules are order-independent and macro-independent--so this work doesn't have to be done when the module is imported. In contrast, when a header file is consumed with `#include`, its contents must be preprocessed and compiled again and again in every translation unit. Precompiled headers, which are compiler memory snapshots, can mitigate those costs, but not as well as named modules. |
+| [Modules](../cpp/modules-cpp.md) | This is the fastest and most robust way to import functionality. Support for importing modules was introduced in C++20. The C++23 standard library introduces the two named modules described in this topic. When you import `std`, you get the standard names such as `std::vector`, `std::cout`, but no extensions, no internal helpers such as `_Sort_unchecked`, and no macros. The order of imports doesn't matter because there are no macro or other side-effects. As a rough approximation of file size, a 250-megabyte PCH file might be represented by an 80-megabyte header unit file, which might be represented by a 25-megabyte module. The reason named modules are faster is because when a named module is compiled into an `.ifc` file and an `.obj` file, the compiler emits a structured representation of the source code that can be loaded quickly when the module is imported. The compiler can do some work (like name resolution) before emitting the `.ifc` file because of how named modules are order-independent and macro-independent--so this work doesn't have to be done when the module is imported. In contrast, when a header file is consumed with `#include`, its contents must be preprocessed and compiled again and again in every translation unit. Precompiled headers, which are compiler memory snapshots, can mitigate those costs, but not as well as named modules. |
+
+If you can use C++20 features and the C++23 standard library, use named modules.
+
+If you can't use C++20 features, use header units. If you can't use C++20 features or header units, use precompiled headers.
 
-If you can use C++20 features and the C++23 standard library, use named modules. If you can't use C++20 features, use header units. If you can't use C++20 features or header units, use precompiled headers. If you can't use C++20 features, header units, or precompiled headers, you are left with `#include`, which is the slowest and least robust method.
+If you can't use C++20 features, header units, or precompiled headers, you're left with `#include`, which is the slowest and least robust method.
 
 ## See also
 
 [Precompiled header files](creating-precompiled-header-files.md)\
-[Overview of modules in C++](modules-cpp.md)\
+[Overview of modules in C++](../cpp/modules-cpp.md)\
 [Tutorial: Import the C++ standard library using modules](../cpp/tutorial-import-stl-named-module.md)\
 [Walkthrough: Import STL libraries as header units](walkthrough-import-stl-header-units.md#approach1)\
 [Walkthrough: Build and import header units in your Visual C++ projects](walkthrough-header-units.md)
@@ -47,9 +47,9 @@ C++20 introduces a modern alternative called *modules*. In C++23, we were able t
 
 Like header files, modules allow you to share declarations and definitions across source files. But unlike header files, modules aren't fragile and are easier to compose because their semantics don't change due to macro definitions or the order in which they're imported. The compiler can process modules significantly faster than it can process `#include` files, and uses less memory at compile time as well. Macro definitions defined in a named module aren't exposed, nor are private implementation details.
 
-For more information about the different ways to include standard library functionality in C++, see [Compare header units, modules, and precompiled headers](compare-header-units-modules-and-precompiled-headers.md).
+For in depth information about modules, see [Overview of modules in C++](../build/modules-cpp.md) That article also discusses consuming the C++ standard library as modules, but uses an older and experimental way of doing it.
 
-For in depth information about modules, see [Overview of modules in C++](modules-cpp.md) That article also discusses consuming the C++ standard library as modules, but uses an older and experimental way of doing it. This article demonstrates the new and best way to consume the standard library. For more information about alternative ways to consume the standard library, see [Different ways to consume the standard library](#different-ways-to-consume-the-standard-library).
+This article demonstrates the new and best way to consume the standard library. For more information about alternative ways to consume the standard library, see [Different ways to consume the standard library](#different-ways-to-consume-the-standard-library).
 
 ## Import the standard library with `std`
 
@@ -221,7 +221,7 @@ In this tutorial, you've imported the standard library using modules. Next, lear
 
 ## See also
 
-[Compare header units, modules, and precompiled headers](compare-header-units-modules-and-precompiled-headers.md)\
+[Compare header units, modules, and precompiled headers](../build/compare-inclusion-methods.md)\
 [Overview of modules in C++](modules-cpp.md)\
 [A Tour of C++ Modules in Visual Studio](https://devblogs.microsoft.com/cppblog/a-tour-of-cpp-modules-in-visual-studio)\
 [Moving a project to C++ named Modules](https://devblogs.microsoft.com/cppblog/moving-a-project-to-cpp-named-modules)