{"id":32,"date":"2007-06-03T09:29:36","date_gmt":"2007-06-03T17:29:36","guid":{"rendered":"https:\/\/2.zoppoz.workers.dev:443\/http\/www.learncpp.com\/?p=32"},"modified":"2025-02-27T00:16:12","modified_gmt":"2025-02-27T08:16:12","slug":"header-files","status":"publish","type":"post","link":"https:\/\/2.zoppoz.workers.dev:443\/https\/www.learncpp.com\/cpp-tutorial\/header-files\/","title":{"rendered":"2.11 — Header files"},"content":{"rendered":"

In lesson 2.8 -- Programs with multiple code files<\/a>, we discussed how programs can be split across multiple files. We also discussed how forward declarations are used to allow the code in one file to access something defined in another file.<\/p>\n

When programs contain only a few small files, manually adding a few forward declarations to the top of each file isn’t too bad. However, as programs grow larger (and make use of more files and functions), having to manually add a large number of (possibly different) forward declarations to the top of each file becomes extremely tedious. For example, if you have a 5 file program, each of which requires 10 forward declarations, you’re going to have to copy\/paste in 50 forward declarations. Now consider the case where you have 100 files and they each require 100 forward declarations. This simply doesn’t scale!<\/p>\n

To address this issue, C++ programs typically take a different approach.<\/p>\n

Header files<\/p>\n

C++ code files (with a .cpp extension) are not the only files commonly seen in C++ programs. The other type of file is called a header file<\/strong>. Header files usually have a .h extension, but you will occasionally see them with a .hpp extension or no extension at all.<\/p>\n

Conventionally, header files are used to propagate a bunch of related forward declarations into a code file.<\/p>\n

\n

Key insight<\/p>\n

Header files allow us to put declarations in one place and then import them wherever we need them. This can save a lot of typing in multi-file programs.\n<\/p><\/div>\n

Using standard library header files<\/p>\n

Consider the following program:<\/p>\n

#include <iostream>\r\n\r\nint main()\r\n{\r\n    std::cout << \"Hello, world!\";\r\n    return 0;\r\n}<\/code><\/pre>\n
This program prints “Hello, world!” to the console using std::cout<\/em>.  However, this program never provided a definition or declaration for std::cout<\/em>, so how does the compiler know what std::cout<\/em> is?<\/p>\n
The answer is that std::cout<\/em> has been forward declared in the “iostream” header file.  When we #include <iostream><\/code>, we’re requesting that the preprocessor copy all of the content (including forward declarations for std::cout) from the file named “iostream” into the file doing the #include.<\/p>\n
\n
Key insight<\/p>\n
When you #include<\/code> a file, the content of the included file is inserted at the point of inclusion.  This provides a useful way to pull in declarations from another file.\n<\/div>\n
Consider what would happen if the iostream<\/em> header did not exist.  Wherever you used std::cout<\/em>, you would have to manually type or copy in all of the declarations related to std::cout<\/em> into the top of each file that used std::cout<\/em>!  This would require a lot of knowledge about how std::cout<\/em> was declared, and would be a ton of work.  Even worse, if a function prototype was added or changed, we’d have to go manually update all of the forward declarations.<\/p>\n
It’s much easier to just #include <iostream><\/code>!<\/p>\n
Using header files to propagate forward declarations<\/p>\n
Now let’s go back to the example we were discussing in a previous lesson.  When we left off, we had two files, add.cpp<\/em> and main.cpp<\/em>, that looked like this:<\/p>\n
add.cpp:<\/p>\n
int add(int x, int y)\r\n{\r\n    return x + y;\r\n}<\/code><\/pre>\n
main.cpp:<\/p>\n
#include <iostream>\r\n\r\nint add(int x, int y); \/\/ forward declaration using function prototype\r\n\r\nint main()\r\n{\r\n    std::cout << \"The sum of 3 and 4 is \" << add(3, 4) << '\\n';\r\n    return 0;\r\n}<\/code><\/pre>\n
(If you’re recreating this example from scratch, don’t forget to add add.cpp<\/em> to your project so it gets compiled in).<\/p>\n
In this example, we used a forward declaration so that the compiler will know what identifier add<\/em> is when compiling main.cpp<\/em>.  As previously mentioned, manually adding forward declarations for every function you want to use that lives in another file can get tedious quickly.<\/p>\n
Let’s write a header file to relieve us of this burden.  Writing a header file is surprisingly easy, as header files only consist of two parts:<\/p>\n
    \n
  1. A header guard<\/em>, which we’ll discuss in more detail in the next lesson (2.12 -- Header guards<\/a>).<\/li>\n
  2. The actual content of the header file, which should be the forward declarations for all of the identifiers we want other files to be able to see.<\/li>\n<\/ol>\n
    Adding a header file to a project works analogously to adding a source file (covered in lesson 2.8 -- Programs with multiple code files<\/a>).<\/p>\n
    If using an IDE, go through the same steps and choose “Header” instead of “Source” when asked.  The header file should appear as part of your project.<\/p>\n
    If using the command line, just create a new file in your favorite editor in the same directory as your source (.cpp) files.  Unlike source files, header files should not<\/em> be added to your compile command (they are implicitly included by #include statements and compiled as part of your source files).<\/p>\n
    \n
    Best practice<\/p>\n
    Prefer a .h suffix when naming your header files (unless your project already follows some other convention).<\/p>\n
    This is a longstanding convention for C++ header files, and most IDEs still default to .h over other options.\n<\/p><\/div>\n
    Header files are often paired with code files, with the header file providing forward declarations for the corresponding code file.  Since our header file will contain a forward declaration for functions defined in add.cpp<\/em>, we’ll call our new header file add.h<\/em>.<\/p>\n
    \n
    Best practice<\/p>\n
    If a header file is paired with a code file (e.g. add.h with add.cpp), they should both have the same base name (add).\n<\/p><\/div>\n
    Here’s our completed header file:<\/p>\n
    add.h:<\/p>\n
    \/\/ We really should have a header guard here, but will omit it for simplicity (we'll cover header guards in the next lesson)\r\n\r\n\/\/ This is the content of the .h file, which is where the declarations go\r\nint add(int x, int y); \/\/ function prototype for add.h -- don't forget the semicolon!<\/code><\/pre>\n
    In order to use this header file in main.cpp, we have to #include it (using quotes, not angle brackets).<\/p>\n
    main.cpp:<\/p>\n
    #include \"add.h\" \/\/ Insert contents of add.h at this point.  Note use of double quotes here.\r\n#include <iostream>\r\n\r\nint main()\r\n{\r\n    std::cout << \"The sum of 3 and 4 is \" << add(3, 4) << '\\n';\r\n    return 0;\r\n}<\/code><\/pre>\n
    add.cpp:<\/p>\n
    #include \"add.h\" \/\/ Insert contents of add.h at this point.  Note use of double quotes here.\r\n\r\nint add(int x, int y)\r\n{\r\n    return x + y;\r\n}<\/code><\/pre>\n
    When the preprocessor processes the #include \"add.h\"<\/code> line, it copies the contents of add.h into the current file at that point.  Because our add.h<\/em> contains a forward declaration for function add()<\/em>, that forward declaration will be copied into main.cpp<\/em>.  The end result is a program that is functionally the same as the one where we manually added the forward declaration at the top of main.cpp<\/em>.<\/p>\n
    Consequently, our program will compile and link correctly.<\/p>\n
    <\/p>\n
    Note: In the graphic above, “Standard Runtime Library” should be labelled as the “C++ Standard Library”.<\/p>\n
    How including definitions in a header file results in a violation of the one-definition rule<\/p>\n
    For now, you should avoid putting function or variable definitions in header files.  Doing so will generally result in a violation of the one-definition rule (ODR) in cases where the header file is included into more than one source file.<\/p>\n
    \n
    Related content<\/p>\n
    We covered the one-definition rule (ODR) in lesson 2.7 -- Forward declarations and definitions<\/a>.\n<\/p><\/div>\n
    Let’s illustrate how this happens:<\/p>\n
    add.h:<\/p>\n
    \/\/ We really should have a header guard here, but will omit it for simplicity (we'll cover header guards in the next lesson)\r\n\r\n\/\/ definition for add() in header file -- don't do this!\r\nint add(int x, int y)\r\n{\r\n    return x + y;\r\n}<\/code><\/pre>\n
    main.cpp:<\/p>\n
    #include \"add.h\" \/\/ Contents of add.h copied here\r\n#include <iostream>\r\n\r\nint main()\r\n{\r\n    std::cout << \"The sum of 3 and 4 is \" << add(3, 4) << '\\n';\r\n\r\n    return 0;\r\n}<\/code><\/pre>\n
    add.cpp:<\/p>\n
    #include \"add.h\" \/\/ Contents of add.h copied here<\/code><\/pre>\n
    When main.cpp<\/code> is compiled, the #include \"add.h\"<\/code> will be replaced with the contents of add.h<\/code> and then compiled.  Therefore, the compiler will compile something that looks like this:<\/p>\n
    main.cpp (after preprocessing):<\/p>\n
    \/\/ from add.h:\r\nint add(int x, int y)\r\n{\r\n    return x + y;\r\n}\r\n\r\n\/\/ contents of iostream header here\r\n\r\nint main()\r\n{\r\n    std::cout << \"The sum of 3 and 4 is \" << add(3, 4) << '\\n';\r\n\r\n    return 0;\r\n}<\/code><\/pre>\n
    This will compile just fine.<\/p>\n
    When the compiler compiles add.cpp<\/code>, the #include \"add.h\"<\/code> will be replaced with the contents of add.h<\/code> and then compiled.  Therefore, the compiler will compile something like this:<\/p>\n
    add.cpp (after preprocessing):<\/p>\n
    int add(int x, int y)\r\n{\r\n    return x + y;\r\n}<\/code><\/pre>\n
    This will also compile just fine.<\/p>\n
    Finally, the linker will run.  And the linker will see that there are now two definitions for function add()<\/code>: one in main.cpp, and one in add.cpp.  This is a violation of ODR part 2, which states, “Within a given program, a variable or normal function can only have one definition.”<\/p>\n
    \n
    Best practice<\/p>\n
    Do not put function and variable definitions in your header files (for now).<\/p>\n
    Defining either of these in a header file will likely result in a violation of the one-definition rule (ODR) if that header is then #included into more than one source (.cpp) file.\n<\/p><\/div>\n
    \n
    Author’s note<\/p>\n
    In future lessons, we will encounter additional kinds of definitions that can be safely defined in header files (because they are exempt from the ODR).  This includes definitions for inline functions, inline variables, types, and templates.  We’ll discuss this further when we introduce each of these.\n<\/p><\/div>\n
    <\/a>Source files should include their paired header <\/i><\/a><\/p>\n
    In C++, it is a best practice for code files to #include their paired header file (if one exists).  This allows the compiler to catch certain kinds of errors at compile time instead of link time.  For example:<\/p>\n
    add.h:<\/p>\n
    \/\/ We really should have a header guard here, but will omit it for simplicity (we'll cover header guards in the next lesson)\r\n\r\nint add(int x, int y);<\/code><\/pre>\n
    main.cpp:<\/p>\n
    #include \"add.h\"\r\n#include <iostream>\r\n\r\nint main()\r\n{\r\n    std::cout << \"The sum of 3 and 4 is \" << add(3, 4) << '\\n';\r\n    return 0;\r\n}<\/code><\/pre>\n
    add.cpp:<\/p>\n
    #include \"add.h\"         \/\/ copies forward declaration from add.h here\r\n\r\ndouble add(int x, int y) \/\/ oops, return type is double instead of int\r\n{\r\n    return x + y;\r\n}<\/code><\/pre>\n
    When add.cpp<\/em> is compiled, the forward declaration int add(int x, int y)<\/code> will be copied into add.cpp<\/em> at the point of the #include.  When the compiler reaches the definition double add(int x, int y)<\/code>, it will note that the return types of the forward declaration and the definition don’t match.  Because functions can’t differ by only a return type, the compiler will error and abort compilation immediately.  In a larger project, this can save a lot of time and help pinpoint where the issue is.<\/p>\n
    \n
    As an aside…<\/p>\n
    Unfortunately, this doesn’t work if it is a parameter with a different type instead of a return type.  This is because C++ supports overloaded functions (functions with the same name but different parameter types), so the compiler will assume a function with a mismatched parameter type is a different overload.  Can’t win em all.\n<\/p><\/div>\n
    If the #include \"add.h\"<\/code> is not present, the compiler won’t catch the issue because it doesn’t see the mismatch.  We have to wait until link time for the issue to surface.<\/p>\n
    We will also see many examples in future lessons where content required by the source file is defined in the paired header.  In such cases, including the header is a necessity.<\/p>\n
    \n
    Best practice<\/p>\n
    Source files should #include their paired header file (if one exists).\n<\/p><\/div>\n
    <\/a>Do not #include .cpp files <\/i><\/a><\/p>\n
    Although the preprocessor will happily do so, you should generally not #include<\/code> .cpp files.  These should be added to your project and compiled.<\/p>\n
    There are number of reasons for this:<\/p>\n