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
+44-31Lines changed: 44 additions & 31 deletions
Display the source diff
Display the rich diff
Original file line number
Diff line number
Diff line change
@@ -7,70 +7,83 @@ ms.custom: intro-overview
7
7
---
8
8
# Cleanup C++ #includes in Visual Studio
9
9
10
-
Starting with Visual Studio 17.7 preview 3, Visual Studio has an `#include` cleanup tool that improves the quality of your code in the following ways:
11
-
- Identifies unused header files in your code and offers to remove them--which improves your build times.
12
-
- Add headers for code that is only working because the header file for it is indirectly included by another header file. This reduces the brittleness of your code because your code doesn't rely on hidden dependencies in other header files.
10
+
Starting with Visual Studio 17.7 preview 3, Visual Studio provides an `#include` cleanup tool that improves the quality of your code in the following ways:
11
+
- Identifies unused header files--improving your build time.
12
+
- Add headers for code that is only working because the header file for it is indirectly included by another header file. This reduces the brittleness of your code by removing its reliance on hidden dependencies.
13
13
14
-
This article provides an overview of what the `#include` cleanup tool in Visual Studio can do.
14
+
This article provides an overview of the `#include` cleanup tool.
15
15
16
16
## Configure #include cleanup
17
17
18
-
To configure the `#include` cleanup tool, go to **Tools** > **Options** > **C/C++** > **Intellisense** and select **Enable #include cleanup**.
18
+
Turn on the `#include` cleanup tool via **Tools** > **Options** > **Text Editor** > **C/C++** > **Code Cleanup** and select **Enable #include cleanup**.
19
19
20
-
:::image type="content" source="media/vs2022_include_cleanup_option.png" alt-text="The Tools options dialog for C/C++ > Intellisense. The area in focus is the Enable # include cleanup checkbox and a dropdown for Remove unused includes tags and Add missing includes tags with the values Refactoring only, dimmed, warning, error, and suggestion.":::
20
+
Then use the dropdowns to configure how you want to be notified about opportunities to remove unused headers and add missing headers:
21
21
22
-
Use the following options to configure how you want to be notified about unused headers and for adding missing headers:
22
+
:::image type="content" source="media/vs2022-include-cleanup-option.png" alt-text="The Tools options dialog opened at Text Editor > C/C++ > Code Cleanup. The Enable # include cleanup checkbox is checked. The dropdowns for Remove unused includes tags and Add missing includes tags are shown. The contents of the dropdown are shown, which are: Refactoring only, Suggestion, Warning, and Error. The Remove unused includes tags dropdown offers the same contents but also adds dimmed.":::
23
23
24
-
**Refactoring only**\
24
+
**Refactoring only:**\
25
25
The cleanup tool only offers to remove unused headers when you invoke refactoring by hovering the cursor over an `#include` to bring up the lightbulb. You can also press Ctrl+period while the cursor is in the `#include` to bring up the refactoring lightbulb:
26
26
27
27
:::image type="content" source="media/include-cleanup-refactor-lightbulb.png" alt-text="When hovering the cursor over # include iostream, a lightbulb appears with the text that # include iostream is not used in this file.":::
28
28
29
-
**Suggestion, Warning, Error**\
30
-
The `#include` cleanup tool will offer to remove unused headers and show a suggestion, warning, or error in the Error List window.
29
+
**Suggestion, Warning, Error:**\
30
+
The `#include` cleanup tool will offer to remove unused headers via a suggestion squiggle, or a warning or error in the Error List window.
31
31
32
-
**Dimmed**\
32
+
**Dimmed:**\
33
33
The `#include` cleanup tool will offer to remove unused header by dimming `#include` in the code editor. Hover your cursor over the dimmed `#include` to bring up the refactoring options to remove the unused header.
34
34
35
-
## Direct vs indirect headers
36
-
37
-
First, some terminology. Direct headers are headers that you explicitly `#include` in your code. Indirect headers are headers included by a header you directly included. You can inadvertently take a dependency on the indirect header. Here's an example:
38
-
39
-
File: header.h
35
+
For the exercises in this article, Remove unused includes tags is set to **Dimmed** and add missing includes tags is set to **Refactoring only**.
40
36
41
-
```cpp
42
-
// header.h
43
-
#include<iostream>
44
-
voidtest() { std::cout << "test";} // uses std::cout from <iostream>, which we include, so <iostream> is a direct header
45
-
```
37
+
## Direct vs indirect headers
46
38
47
-
File: source.cpp
39
+
First, some terminology. Direct headers are headers that you explicitly `#include` in your code. Indirect headers are included by a header you directly include. You can inadvertently take a dependency on the indirect header. Here's an example:
48
40
49
41
```cpp
50
-
#include "header.h"
51
-
// you should explicitly #include <iostream> because you're using std::cout in this file
42
+
#include<stdlib.h>
52
43
53
-
test(); // outputs "test"
54
-
std::cout << "Only works because header1.h includes <iostream>"; // <iostream> is an indirect header because you rely on rely on header1.h to provide it
44
+
intmain()
45
+
{
46
+
int charSize = CHAR_BIT; // CHAR_BIT is defined in limits.h
47
+
}
55
48
```
56
49
57
-
In this example, if `header1.h` is updated to no longer include `<iostream>`, your code will break in `source.cpp` because it doesn't directly include a dependency it needs. It was relying on `header1.h` to provide it. Per the C++ guidelines, it's better to explicitly `#include <iostream>` in `source.cpp` so that your code isn't subject to brittleness caused by changes to header files. For more information about the guideline to avoid dependencies on names brought in implicitly when #including a header, see [C++ Core Guidelines SF.10](https://isocpp.github.io/CppCoreGuidelines/CppCoreGuidelines#sf10-avoid-dependencies-on-implicitly-included-names). The C++ include cleanup tool helps you find and fix these issues like this.
50
+
In this example, `CHAR_BIT` is defined in `limits.h`. The reason this code compiles is because `stdlib.h` includes `limits.h` If `stdlib.h` ever stopped including `limits.h`, this code would break because it doesn't directly include a dependency it needs. It's relying on `stdlib.h` to provide it.
51
+
52
+
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). The C++ include cleanup tool helps you find and fix issues like this.
58
53
59
54
## Unused headers
60
55
61
-
As your code evolves, you may no longer need some header files. This is hard to track in complex projects and over time your build time may be impacted by the compiler processing header files that aren't needed. The C++ include cleanup tool helps you find and remove these unused headers. For example:
56
+
As your code evolves, you may no longer need some header files. This is hard to track in a complex project, and over time your build time may be impacted by the compiler processing header files that aren't even used. The C++ include cleanup tool helps you find and remove these unused headers. For example:
62
57
63
58
```cpp
64
-
#include<cstdlib>
59
+
#include<stdlib.h>
65
60
#include<iostream>
66
61
67
62
intmain()
68
63
{
69
-
int x = std::rand(); // std::rand is defined in <cstdlib>
70
-
// std::cout << "x is: " << x; // we no longer output x, so we don't need <iostream>
64
+
int charSize = CHAR_BIT; // CHAR_BIT is defined in limits.h
65
+
// std::cout << "charSize = " << charSize << std::endl; // Commenting this line means <iostream> isn't needed
71
66
}
72
67
```
73
68
69
+
In this case, `#include <iostream>` is dimmed because it isn't used since `std::cout` is commented out. Hover your cursor over the dimmed `#include` to bring up the refactoring options to remove the unused header:
70
+
71
+
:::image type="content" source="media/include-cleanup-refactor-lightbulb.png" alt-text="#include iostream is dimmed. Hovering the cursor over that line shows the refactor lightbulb and a link to Show potential fixes.":::
72
+
73
+
Choose **Show potential fixes** (or click the lightbulb) to bring up the refactoring menu. Choose **Remove unused #include** to remove the unused header:
74
+
75
+
:::image type="content" source="media/vs2022-include-cleanup-refactor-options.png" alt-text="Three refactoring options are shown: Remove # include iostream, remove all unused includes, and Add all transitively used and remove all unused # includes.":::
76
+
77
+
It might be surprising to you that both `stdlib.h` and `iostream` are dimmed. The reason is that nothing in `stdlib.h` is used in this file. Because it includes `#include <limits.h>`, which defines `CHAR_BIT`, we are relying on it indirectly.
78
+
79
+
Choose **Add all transitively used and remove all unused # includes.** to remove the unused header and add any headers that are transitively used by the code in the file. In this case, `#include <limits.h>` is added because `CHAR_BIT` is defined in that header, and `stdlib.h` was indirectly including that for us. And `stdlib.h` is removed because we aren't using anything from it.
80
+
81
+
Now let's see how adding headers work by uncommenting the line: `// std::cout << "charSize = " << charSize;`. This code now uses `std::cout`, but it doesn't directly include the header that defines it. Hover your cursor over that line and choose Show potential fixes (or click the lightbulb). Then choose **Add '#include <iostream'**.
82
+
83
+
Now your code compiles again, but does so by only bringing in the headers that it is actually using.
84
+
85
+
In this brief overview, you've seen how the #include cleanup tool can help you remove unused headers and add missing headers. For more information, see the walkthrough and the reference.
0 commit comments