清理 Visual Studio 中的 C/C++ 包含项

从 Visual Studio 17.8 预览版 1 开始,Visual Studio 提供了一项 #include 清理功能,可通过以下方式提高代码的质量:

Visual Studio提供清理#include功能,可通过以下方式提高代码的质量:

  • 建议为那些仅仅因为另一个头文件间接包含了所需头文件才得以编译的代码添加头文件。
  • 移除未使用的头文件 - 提高编译时间和代码整洁度。

默认关闭 Include Cleanup。 若要了解如何配置它,请参阅在 Visual Studio 中配置 C/C++ Include Cleanup。

直接标头与间接标头

一些术语:

  • 直接头文件是指你在代码中显式 #include 的头文件。
  • 之所以会包含某个间接头文件,是因为你直接包含的头文件包含了它。 还可以说 transitively 包含了间接标头。

Include Cleanup 会分析代码并确定哪些标头未使用,以及哪些标头是间接包含的。 请看下面的头文件:

// myHeader.h

#include <string>
#include <iostream>

void myFunc()
{
    std::string s = "myFunc()\n";
    std::cout << s;
}

以及使用它的程序:

// myProgram.cpp
#include "myHeader.h"

int main()
{
    std::string s = "main()"; // string is indirectly included by myHeader.h
    std::cout << s; // cout is indirectly included by myHeader.h
    myFunc();
}

myHeader.h 是直接标头,因为 myProgram.cpp 显式包含它。 myHeader.h 包含 <string> 和 <iostream>,因此这些标头是间接标头。

问题是 myProgram.cpp 使用 std::string 和 std::cout,但不直接包含定义它们的标头。 此代码编译是因为 myHeader.h 包括这些标头。 此代码很脆弱,因为如果 myHeader.h 哪天不再包含其中任意一个头文件,myProgram.cpp 就无法继续编译了。

根据 C++ 准则,最好为所有依赖项显式包含相应的头文件,从而避免代码因头文件的变更而变得脆弱。 有关该准则的详细信息,请参阅《C++ 核心准则》中的 SF.10:避免依赖隐式命名的名称#include。

Include Cleanup 会对代码进行分析,以识别未使用和间接包含的标头。 它基于在 Visual Studio 中配置 C++ #include 工具中所述的设置提供反馈。 反馈以错误列表警告和建议的形式提供。 有关 Include Cleanup 提供的反馈的更多信息,请参阅 Include Cleanup 消息。

未使用的标头

随着代码的发展,可能不再需要一些头文件。 在复杂项目中,很难理清这些标头。 随着时间的推移,生成可能需要更长的时间,因为编译器处理不必要的头文件。 Include Cleanup 可帮助你查找和删除未使用的标头。 例如,如果在 myFunc() 中注释掉 myProgram.cpp,会怎样:

// myProgram.cpp
#include "myHeader.h"

int main()
{
    std::string s = "main()"; // string is indirectly included from myHeader.h
    std::cout << s; // cout is indirectly included from myHeader.h
    // myFunc(); // directly included from myHeader.h
}

在下面的屏幕截图中,#include "myHeader.h"显示为灰显(这是 在 Visual Studio 中配置 C++ #include 工具中介绍的一项设置),因为由于 myFunc() 已被注释掉,它不再是必需的。

将光标悬停在灰显的 #include 上,即可显示快速操作菜单。 选择灯泡(或选择 “显示潜在修复 ”链接),查看与未使用的文件相关的操作:

显示了三个重构选项:删除 #include myHeader.h、删除所有未使用的 #include,以及添加所有传递使用的 #include 并删除所有未使用的 #include。

添加传递性使用的标头

你可能会选择删除未使用的头文件,但该操作会破坏代码,因为 <string> 和 <iostream> 是通过 myheader.h 间接包含进来的。

我们可以改为选择“添加所有可传递使用的 #include,并移除所有未使用的 #include”。 这会移除未使用的头文件 myHeader.h,但也会添加通过 myHeader.h 间接包含进来的所有正在使用的头文件。 在本例中,结果是将 #include <string> 和 #include <iostream> 添加到 myProgram.cpp,并移除 #include "myHeader.h":

// myProgram.cpp
#include <iostream>
#include <string>

int main()
{
    std::string s = "main()"; // string is directly included from <string>
    std::cout << s; // cout is directly included from <string>
    // MyFunc();
}

该工具不会更新注释,但可以看到代码现在正在直接使用 std::string 和 std::cout。 这段代码不再脆弱了,因为它不再依赖 myHeader.h 来包含其他所需的头文件。

最佳做法

在先添加间接包含的头文件之前,请勿移除似乎未使用的头文件。 你的代码可能依赖于某个原本未被使用的头文件间接包含的内容。 首先添加可传递使用的标头。 然后,当你删除未使用的头文件时,就不会因为缺少那些由你删除的某个头文件间接包含的头文件而出现编译错误。

执行此操作的一种方法是:

  • 将 “添加缺失 的包括清理”设置包括建议级别设置为 “建议 ”(工具>选项>文本编辑器>C/C++>代码清理)。
  • 将 删除未使用 include 的建议级别 设置为 建议。

执行此操作的一种方法是:

  • 设置“包括清理”设置的下拉列表,以便选择如何突出显示缺失的 #include 语句(工具>>>>>>清理)。
  • 将 选择如何突出显示未使用的 #include 语句 设置为 建议。

然后:

  1. 在错误列表中,确保将筛选器设置为 Build + IntelliSense。
  2. 查找“此文件中使用了来自 #include x 的内容,且该内容是通过传递包含引入的”这种情况。
  3. 将光标悬停在带有建议的行上。 从灯泡下拉菜单中,选择“添加所有传递使用的包含项”。
  4. 在项目中重复这些步骤,直到与传递包含相关的所有建议都得到处理。
  5. 移除未使用的 include:在错误列表中,查找“#include x 未在此文件中使用”的实例。
  6. 将光标悬停在未使用的标头上。 从灯泡下拉列表中,选择“移除所有未使用的 include”。
  7. 重复项目中的这些步骤,直到解决所有 Include Cleanup 建议。

在这个简短的概述中,你看到了 Include Cleanup 如何帮助你移除未使用的标头,并添加原先通过间接方式包含的标头。 此过程可帮助你保持代码干净、可能更快地生成,并减少代码的脆弱性。

另请参阅

在 Visual Studio 中配置 C/C++ 清理包含
包括清理消息