LLVM Include Cleaner: Handling Double Includes For Same-Class Files

Hey there, fellow developers! Let's dive into a topic that often pops up when working with C++ and build systems like LLVM: the sometimes perplexing world of header inclusions. Specifically, we're going to chat about the general consensus and best practices surrounding what's known as a "double include" – that is, including the same header file in both the .cpp source file and its corresponding .h header file for the same class. This might seem like a minor detail, but as many of you know, even small things can impact code clarity, build times, and the effectiveness of tools like misc-include-cleaner.

The Dilemma of Double Includes: When to Include What?

So, you've got a function in your class that, let's say, returns a std::string. Naturally, you declare this function in your header file (.h), and the actual implementation lives in your source file (.cpp). Now, here's where the misc-include-cleaner tool often chimes in with a warning. If you include <string> only in your .h file where std::string is declared, the tool might flag it, stating that "no header providing 'std::string' is directly included" in the .cpp file. This forces many developers to include <string> in both the .h and the .cpp file to keep the linter happy.

But is this always necessary? Many of us have a hunch, and often a strong one, that including the necessary header in the .h file should be sufficient, especially when the .cpp file is directly associated with that header (i.e., they share the same base name). The argument is that if the .h file declares it, and the .cpp file implements it, the dependency is clear. Duplicating the include in the .cpp file feels like redundancy. It adds lines of code, potentially increases compile times (though modern compilers are quite good at handling this), and might obscure the actual dependencies. The core idea is that the header file serves as the public interface, and any type used within that interface should have its defining header included there. The implementation file should then implicitly inherit this by including the header.

This leads to a crucial question: What's the general opinion on this specific scenario? Should misc-include-cleaner continue to issue a warning even in this case, implying that we must include necessary headers in both files? Or could the check be adjusted to recognize this common and often acceptable pattern? Perhaps it could be made configurable, allowing developers to decide whether this specific type of double include warrants a warning in their project. The flexibility would empower teams to adopt practices that best suit their workflow and coding standards, while still leveraging the tool for genuinely problematic include situations.

The Case for Header-Only Includes: Clarity and Efficiency

Let's delve deeper into why the argument for including headers only where they are directly needed, primarily in the header file for declarations, holds significant weight. The primary role of a header file is to define the public interface of a class, function, or module. This means it should contain all the information necessary for other files to understand how to use what's being exposed. When you declare a function that returns std::string, the header file is the logical place to include <string>. This tells any file including your header, "Hey, std::string is a type you'll encounter here, and here's how to find its definition." If the .cpp file only includes its corresponding .h file, it effectively gains access to all the declarations and necessary type information defined in that header, including the fact that std::string is used.

From an efficiency standpoint, especially in large projects, minimizing redundant includes can be beneficial. While compilers are sophisticated, including a header repeatedly can still contribute to longer compilation times. More importantly, it can lead to larger object files. When a tool like misc-include-cleaner flags this specific scenario, it encourages a pattern that might not be the most efficient or the most intuitive for C++ developers. The warning implies that the .cpp file is somehow