You signed in with another tab or window. Reload to refresh your session.You signed out in another tab or window. Reload to refresh your session.You switched accounts on another tab or window. Reload to refresh your session.Dismiss alert
Copy file name to clipboardExpand all lines: docs/ide/include-cleanup-overview.md
+16-15Lines changed: 16 additions & 15 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -1,7 +1,7 @@
1
1
---
2
2
title: "Clean up C/C++ #includes in Visual Studio"
3
3
description: "Learn about using C/C++ include cleanup in Visual Studio to remove unused headers, and transitively add indirect headers needed in your project."
4
-
ms.date: 10/04/2023
4
+
ms.date: 10/5/2023
5
5
ms.topic: "overview"
6
6
ms.custom: intro-overview
7
7
---
@@ -21,7 +21,7 @@ First some terminology:
21
21
- A direct header is a header that you explicitly `#include` in your code.
22
22
- An indirect header is a header that you don't explicitly `#include`, but that is included by a header file that you do directly include. We also say that an indirect header is included `transitively`.
23
23
24
-
Include cleanup analyzes your code and determines which headers aren't used and which are indirectly included. Consider the following header file and the program that uses it:
24
+
Include cleanup analyzes your code and determines which headers aren't used and which are indirectly included. Consider the following header file and the program that #includes it:
25
25
26
26
```cpp
27
27
// myHeader.h
@@ -50,17 +50,17 @@ int main()
50
50
}
51
51
```
52
52
53
-
`myHeader.h` is a direct header because `myProgram.cpp` explicitly includes it. `myHeader.h` includes `<string>` and `<iostream>`, so those are indirect headers, as far as `myProgram.cpp` is concerned.
53
+
`myHeader.h` is a direct header because `myProgram.cpp` explicitly includes it. `myHeader.h` includes `<string>` and `<iostream>`, so those are indirect headers.
54
54
55
-
The issue is that `myProgram.cpp` uses `std::string` and `std::cout`, but doesn't directly include the headers that define those types. This code happens to compile because `myHeader.h` includes those headers. This code is brittle because it depends on `myHeader.h`to include those headers. If `myHeader.h`ever stopped including either one of them, this code would break.
55
+
The issue is that `myProgram.cpp` uses `std::string` and `std::cout`, but doesn't directly include the headers that define them. This code happens to compile because `myHeader.h` includes those headers. This code is brittle because if `myHeader.h` ever stopped including either one of them, `myProgram.cpp` wouldn't compile anymore.
56
56
57
-
Per the C++ guidelines, it's better to explicitly include headers for all your dependencies so that your code isn't subject to brittleness caused by changes to header files. For more information, see [C++ Core Guidelines SF.10](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#sf10-avoid-dependencies-on-implicitly-included-names).
57
+
Per the C++ guidelines, it's better to explicitly include headers for all of your dependencies so that your code isn't subject to brittleness caused by changes to header files. For more information, see [C++ Core Guidelines SF.10](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#sf10-avoid-dependencies-on-implicitly-included-names).
58
58
59
-
Include cleanup helps you find and fix issues like this. It analyzes your code and determines which headers are indirectly included and which aren't used at all. It provides feedback, based on settings described in [Config the C++ #include tool in Visual Studio](include-cleanup-config.md). Those settings determine whether suggestions to remove unused headers and add indirectly included headers via warnings, suggestions, and so on.
59
+
Include cleanup helps you find and fix issues like this. It analyzes your code and determines which headers are indirectly included and which aren't used at all. It provides feedback, based on settings described in [Config the C++ #include tool in Visual Studio](include-cleanup-config.md). Those settings determine how to notify you about opportunities to remove unused headers and add indirectly included headers. You can be notified by error list warnings, suggestions, and so on.
60
60
61
61
## Unused headers
62
62
63
-
As your code evolves, you may no longer need some header files. This is hard to keep track of in a complex project. Over time your build time may be slowed by the compiler processing unnecessary header files. Include cleanup helps you find and remove unused headers. For example, what if `myFunc()` is commented out in `myProgram.cpp`:
63
+
As your code evolves, you may no longer need some header files. This is hard to keep track of in a complex project. Over time, your build time may be slowed by the compiler processing unnecessary header files. Include cleanup helps you find and remove unused headers. For example, what if `myFunc()` is commented out in `myProgram.cpp`:
64
64
65
65
```cpp
66
66
// myProgram.cpp
@@ -82,9 +82,9 @@ Hover your cursor over the dimmed `#include` to bring up the quick action menu.
82
82
83
83
## Add transitively used headers
84
84
85
-
We could choose to remove the unused header file, but that breaks the code since `<string>` and `<iostream>`isn't indirectly included via `myheader.h`.
85
+
We could choose to remove the unused header file, but that breaks the code since `<string>` and `<iostream>`are indirectly included via `myheader.h`.
86
86
87
-
Instead, we can choose **Add all transitively used and remove all unused #includes**. This removes the unused header `myHeader.h`, but also adds any headers that are being used that were indirectly included by the removed header file. In this case, `#include <string>` and `#include <iostream>` are added because they're indirectly included by `myHeader.h`, which is then removed. You can think of the order of operations followed by include cleanup as:
87
+
Instead, we can choose **Add all transitively used and remove all unused #includes**. This removes the unused header `myHeader.h`, but also adds any headers that are being used that were indirectly included by the removed header file. In this case, `#include <string>` and `#include <iostream>` are added because they're indirectly included by `myHeader.h`, which is then removed. A good order of operations for using include cleanup is:
88
88
89
89
- determine which indirect header files are being used
90
90
- add `#include`s for the indirect header files
@@ -109,16 +109,17 @@ The tool doesn't update the comments, but you can see that the code is now using
109
109
110
110
## Using include cleanup with large codebases
111
111
112
-
If your codebase is large, the recommended approach to clean up the #includes is to first add direct headers where indirect headers are used. After you have done this for all indirect headers in the file, then remove the unused includes.
112
+
If your codebase is large, the recommended approach is to clean up the #includes by first adding direct headers where indirect headers are used. After you have done that for all indirect headers in the file, then remove any unused includes.
113
113
114
114
To do this, set your the include cleanup setting for **Add missing includes suggestion level** to **Suggestion** (**Tools** > **Options** > **Text Editor** > **C/C++** > **Code Cleanup**). Also set **Remove unused includes suggestion level** to **Suggestion**.
115
115
116
-
1. In the error list, make sure the filter is set to **Build + IntelliSense** and look for an instance of 'Content from #include x is used in this file and transitively included'.
116
+
1. In the error list, make sure the filter is set to **Build + IntelliSense**.
117
+
1. Look for instances of 'Content from #include x is used in this file and transitively included'.
117
118
1. Hover your cursor over line with the suggestion and invoke the quick action menu by clicking the broom or pressing Ctrl+period.
118
-
1. Choose **Add all transitively used includes**
119
-
1.In the error list, look for all instances of `#include x is not used in this file'.
120
-
1. Hover your cursor over the unused header and choose **Remove #include <header>**.
121
-
1. Repeat these steps until there are no more suggestions about transitively include includes or unused includes and the file compiles cleanly.
119
+
1. Choose **Add all transitively used includes**.
120
+
1.Remove unused includes: in the error list, look for all instances of `#include x is not used in this file'.
121
+
1. Hover your cursor over the unused header and choose **Remove #include \<header\>**.
122
+
1. Repeat these steps until there are no more suggestions about transitively include includes or unused includes.
122
123
1. Repeat these steps for the other files in your project that you wish to cleanup.
123
124
124
125
In this brief overview, you've seen how include cleanup can help you remove unused headers, and add headers that were indirectly included. This helps you keep your code clean, potentially build faster, and reduces the brittleness of your code.
0 commit comments