Navigation



1.9 — Header files

Code files (with a .cpp extension) are not the only files commonly seen in programs. The other type of file is called a header file, sometimes known as an include file. Header files almost always have a .h extension. The purpose of a header file is to hold declarations for other files to use.

Using standard library header files

Consider the following program:

#include <iostream>
int main()
{
    using namespace std;
    cout << "Hello, world!" << endl;
    return 0;
}

This program prints “Hello, world!” to the console using cout. However, our program never defines cout, so how does the compiler know what cout is? The answer is that cout has been declared in a header file called “iostream”. When we use the line #include <iostream>, we are telling the compiler to locate and then read all the declarations from a header file named “iostream”.

Keep in mind that header files typically only contain declarations. They do not define how something is implemented, and you already know that your program won’t link if it can’t find the implementation of something you use. So if cout is only defined in the “iostream” header file, where is it actually implemented? It is implemented in the runtime support library, which is automatically linked into your program during the link phase.

A library is a package of code that is meant to be reused in many programs. Typically, a library includes a header file that contains declarations for everything the library wishes to expose (make public) to users, and a precompiled object that contains all of the implementation code compiled into machine language. These libraries typically have a .lib or .dll extension on Windows, and a .a or .so extension on Unix. Why are libraries precompiled? First, since libraries rarely change, they do not need to be recompiled often, if ever. It would be a waste of time to compile them every time you wrote a program that used them. Second, because precompiled objects are in machine language, it prevents people from accessing or changing the source code, which is important to businesses or people who don’t want to make their source code available for intellectual property reasons.

Writing your own header files

Now let’s go back to the example we were discussing in the previous lesson. When we left off, we had two files, add.cpp and main.cpp, that looked like this:

add.cpp:

int add(int x, int y)
{
    return x + y;
}

main.cpp:

#include <iostream>

int add(int x, int y); // forward declaration using function prototype

int main()
{
    using namespace std;
    cout << "The sum of 3 and 4 is " << add(3, 4) << endl;
    return 0;
}

We’d used a forward declaration so that the compiler would know what add was when compiling main.cpp. As previously mentioned, writing forward declarations for every function you want to use that lives in another file can get tedious quickly.

Header files can relieve us of this burden. A header file only has to be written once, and it can be included in as many files as needed. This also helps with maintenance by minimizing the number of changes that need to be made if a function prototype ever changes (eg. by adding a new parameter).

Writing our own header files is surprisingly easy. Header files consist of two parts. The first part is called a header guard, which is discussed in the next lesson (on the preprocessor). The second part is the actual content of the .h file, which should be the declarations for all of the functions we want other files to be able to see. Our header files should all have a .h extension, so we’ll call our new header file add.h:

add.h:

#ifndef ADD_H
#define ADD_H

int add(int x, int y); // function prototype for add.h

#endif

In order to use this header file in main.cpp, we have to include it. Here is the new main.cpp:

main.cpp that includes add.h:

#include <iostream>
#include "add.h" // this brings in the declaration for add()

int main()
{
    using namespace std;
    cout << "The sum of 3 and 4 is " << add(3, 4) << endl;
    return 0;
}

When the compiler compiles the #include "add.h" line, it copies the contents of add.h into the current file. Because our add.h contains a function prototype for add(), this prototype is now being used as a forward declaration of add()!

Consequently, our program will compile and link correctly.

You’re probably curious why we use angled brackets for iostream, and double quotes for add.h. The answer is that angled brackets are used to tell the compiler that we are including a header file that was included with the compiler. The double-quotes tell the compiler that this is a header file we are supplying, which causes it to look for that header file in the current directory containing our source code first.

Rule: Use angled brackets to include header files that come with the compiler. Use double quotes to include any other header files.

Another commonly asked question is “why doesn’t iostream have a .h extension?”. The answer is, because iostream.h is a different header file than iostream is! To explain requires a very short history lesson.

When C++ was first created, all of the files in the standard runtime library ended in .h. Life was consistent, and it was good. The original version of cout and cin lived in iostream.h. When the language was standardized by the ANSI committee, they decided to move all of the functions in the runtime library into the std namespace (which is generally a good idea). However, this presented a problem: if they moved all the functions into the std namespace, none of the old programs would work any more!

To try to get around this issue and provide backwards compatibility for older programs, a new set of header files was introduced that use the same names but lack the .h extension. These new header files have all their functionality inside the std namespace. This way, older programs that include #include <iosteam.h> do not need to be rewritten, and newer programs can #include <iostream>.

Make sure when you include a header file from the standard library that you use the non .h version if it exists. Otherwise you will be using a deprecated version of the header that is no longer supported.

As a side note, many headers in the standard library do not have a non .h version, only a .h version. For these files, it is fine to include the .h version. Many of these libraries are backwards compatible with standard C programming, and C does not support namespaces. Consequently, the functionality of these libraries will not be accessed through the std namespace. Also, when you write your own header files, they will all have a .h extension, since you will not be putting your code in the std namespace.

Rule: use the non .h version of a library if it exists, and access the functionality through the std namespace. If the non .h version does not exist, or you are creating your own headers, use the .h version

Header file best practices

Here are a few best practices for creating your own header files.

  • Always include header guards.
  • Do not declare variables in header files unless they are constants. Header files should generally only be used for declarations.
  • Do not define functions in header files unless they are trivial. Doing so makes your header files harder for humans to read.
  • Each header file should have a specific job, and be as independent as possible. For example, you might put all your declarations related to functionality A in A.h and all your declarations related to functionality B in B.h. That way if you only care about A later, you can just include A.h and not get any of the stuff related to B.
  • Try to include as few other header files as possible in your header files.
1.10 — A first look at the preprocessor
Index
1.8 — Programs with multiple files

211 comments to 1.9 — Header files

  • mm

    Hi
    I tried to use the add() function in a Class.
    But I got this error :
    error LNK2019: unresolved external symbol “public: int __thiscall Class1::add(int,int)” (?add@Class1@@QAEHHH@Z) referenced in function _main
    error LNK1120: 1 unresolved externals

    I am using Microsoft Visual Studio 2008. Created a win32 Console Application.

    I have put the 3 files below. Main.cpp Class1.cpp and Class1.h
    There seems to be a problem Linking but I can not figure out why.
    Thanks a lot for your help, greatly appreciate your help.

    FILE: MAIN.cpp_____________________________________________

    #include
    #include
    #include “Class1.h”
    int main()
    {
    Class1 c;
    int res=c.add(3, 4);
    return 0;
    }
    _____________________________________________
    FILE: Class1.cpp_____________________________________________
    #include

    class Class1
    {
    public:
    int add(int x, int y)
    {
    return x + y;
    }
    };

    _____________________________________________
    FILE:Class1.h_____________________________________________
    #ifndef CLASS1_H
    #define CLASS1_H

    class Class1
    {
    public:
    int add(int x, int y); // function prototype
    };

    #endif

  • [...] Now, when the compiler is compiling main.cpp, it will know what add is. Using this method, we can give files access to functions that live in another file. However, as programs grow larger and larger, it becomes tedious to have to forward declare every function you use that lives in a different file. To solve that problem, the concept of header files was introduced. We discuss header files in the lesson on header files. [...]

  • [...] Now, when the compiler is compiling main.cpp, it will know what add is. Using this method, we can give files access to functions that live in another file. However, as programs grow larger and larger, it becomes tedious to have to forward declare every function you use that lives in a different file. To solve that problem, the concept of header files was introduced. We discuss header files in the lesson on header files. [...]

  • Nitin

    amazing i find this website to be very helpful

  • The following source for
    main.cpp, add.cpp and add.h
    worked using Microsoft Visual C++ Express 2010

    I still don’t understand the first two lines in the add.h file.

    #ifndef MATH_H

    and

    #define MATH_H

    My first impression was “ifndef” was a typo of “define” with “MATH_H” being a derivative of “math.h”. Apparently I’m wrong since it does in fact work. I just don’t understand the where and how of those two lines substance.

    #define

    makes sense

    #ifndef

    I don’t understand. It looks like “define” scrambled.

    MATH_H

    I don’t understand. “math.h” would seem to make more sense. I surmise “MATH_H” is a Microsoft addon to the standard library though I would think that would require an include statement, not a define.

  • I see the next page, Section 1.10 has this to say:
    To prevent this from happening, we use header guards, which are conditional compilation directives that take the following form:

    #ifndef SOME_UNIQUE_NAME_HERE
    #define SOME_UNIQUE_NAME_HERE   
    
    // your declarations here   
    
    #endif
    

    SO, the “MATH_H” is merely some unique name to ensure the particular header file is not included more than once. I still don’t understand the

    #ifndef</PRE part though.
  • Deceit

    Ok I question first is the Header suppose to be made separate from the .cpp? or is the header suppose to be included inside the .cpp?

    I’m using Visual studio 2010

    ok this is what I’ve been trying to do. I first start making a header by going to File – New – File – Visual C++ – Header File C (.h)

    I input:

    #ifndef ADD_H
    #define ADD_H

    int add(int x, int y); // function prototype for add.h

    #endif

    After that I save it as ADD_H

    After that I make a new .Cpp (File – New – Win32 Console Applications)

    then I input:

    #include
    #include “stdafx.h”
    #include “add.h” // this brings in the declaration for add()

    int main()
    {
    using namespace std;
    cout << "The sum of 3 and 4 is " << add(3, 4) <.<

    • Ashoenew

      I take it you had the same prob I had did you come up with a link error or did it run fine? you didn’t specify

      • Deceit

        Ok I understand wat I did wrong I didn’t the header file that I made into
        to .cpp file that i’m using it for
        BUT! everything said it was fine but… when I tried to complied with an fail… this is the error code

        1>—— Build started: Project: Lesson1.9, Configuration: Debug Win32 ——
        1> Lesson1.9.cpp
        1>c:\users\culex\documents\visual studio 2010\projects\lesson1.9\lesson1.9\add.h(5): error C2447: ‘{‘ : missing function header (old-style formal list?)
        ========== Build: 0 succeeded, 1 failed, 0 up-to-date, 0 skipped ==========

        P.S. I wrote more on my original but.. it cutted it off…

  • Ashoenew

    Ok so im using Microsoft visual c++ express 2010 and I followed the instructions completely and I came up with a link error.? so any help? here is what i have for add.h

    #ifndef ADD_H
    #define ADD_H

    int add(int x, int y);

    #endif

    // this is what i have for main.cpp

    #include “stdafx.h”
    #include
    #include “add.h”

    int main()
    {
    using namespace std;
    cout << "The sum of 3 and 4 is:" << add(3,4) <—— Build started: Project: add, Configuration: Debug Win32 ——
    1> add.cpp
    1>add.obj : error LNK2019: unresolved external symbol “int __cdecl add(int,int)” (?add@@YAHHH@Z) referenced in function _main
    1>C:\Users\\add\Debug\add.exe : fatal error LNK1120: 1 unresolved externals
    ========== Build: 0 succeeded, 1 failed, 0 up-to-date, 0 skipped ==========

    • Ashoenew

      i did finish the program it just didn’t post it all.

      • Ashoenew

        what did i do wrong or why did i get a link error? thanks in advance. also thanks for being patient.

        • Deceit

          Ok… this is how to make header files on Microsoft Visual 2010 and insert it into your other projects

          Part1: First of all you’ll have to create a header file first go to

          File –

          New –

          File –

          Visual C++ –

          Header File – (The file will be named by itself but I recommend you change it to the name you want by going to save as)[Also there is no need to add ".h" when naming it, it will be inserted by itself]{Also I named my “add” so i’ll be using my name for example}

          • Deceit

            Part 2

            Now to input the code
            Like this:

            #ifndef ADD_H
            #define ADD_H

            int add(int x, int y )
            {
            return x + y;
            }
            #endif

            After that save and close project

            Part 3 Your Project

            Insert the code:

            // Lesson1.9.cpp : Defines the entry point for the console application.
            //

            #include “stdafx.h”
            #include
            #include “add.h” // this brings in the declaration for add()

            int main()
            {
            using namespace std;
            cout << "The sum of 3 and 4 is " << add(3, 4) << endl;
            return 0;
            }

            Save it and close

            • Deceit

              Part 4

              Now I suggest you start making a header folder for you header files

              Now find your header file and then copy

              After that find your project you just saved
              {Good chance it will be where mine is}[Documents-Visual Studio 2010-Projects]

              After that enter your project and go to “Name of your project”
              For example my project was named “Lesson 1.9″
              {Projects- Lesson 1.9 – {When you see other head files insert it in there}

              Ok now open your “Project” and on the right of screen there should be “Solution Screen” and under Headers add your header

              AND BAM your done try running it if it doesn’t work all hope is lost for you.. I guess. Well I got mine to work :)

  • [...] KNOWLEDGE FOR THIS PROGRAM Header Files – How To Use Them Class – Data Structure Enumerated List Typedef Do/While Loop Passing a Value By Reference Constant [...]

  • sanusha

    #include
    #include
    #include “Dll.h”
    #include “guid.h”
    can u say the meaning of these header files

  • [...] KNOWLEDGE FOR THIS PROGRAM Header Files – How To Use Them Class – What Is It? Do/While Loop Passing a Value By Reference Roman Numerals – How Do You Convert [...]

  • [...] KNOWLEDGE FOR THIS PROGRAM Header Files – How To Use Them Class – What Is It? How To Read Data From A File String – Getline Array – Cin.Getline Strcpy – Copy [...]

  • yuvadius

    why would a header file include another header file?
    arn’t you supose to just declare stuff in a header file.
    in that case i don’t see why header file will even include another header file

  • artxworks

    so add.cpp is still needed? since we don’t need to write the actual code in the header add.h ….

    #ifndef ADD_H_INCLUDED // I don’t know why it has that “ADD_H_INCLUDED
    #define ADD_H_INCLUDED // same for this one and the #endif …. can I change it to other names??? say ADD_H_WHATEVERIWANTHERE???

    int add(int x, int y);

    #endif // ADD_H_INCLUDED

    I tried it in Code::Blocks and it worked! XD

  • [...] – Line 01, 02 and 22 are part of the so-called “include guard”. When C++ includes this header file the first time the name PERSON_H is assigned to it. If you try to include this header file a second time, which would result in an error, C++ checks if the name PERSON_H already exists. Since PERSON_H already exists from the first include, the header file is not included again which prevents an error. – More on the include guard can be found here: learncpp [...]

  • [...] Now, when the compiler is compiling main.cpp, it will know what add is. Using this method, we can give files access to functions that live in another file. However, as programs grow larger and larger, it becomes tedious to have to forward declare every function you use that lives in a different file. To solve that problem, the concept of header files was introduced. We discuss header files in the lesson on header files. [...]

  • [...] the lesson on header files, you learned that you can put functions inside header files in order to reuse them in multiple [...]

  • gu_obos

    As an FYI to anyone else having issues with Visual Studio 2012 and having issues with with building:

    If precompiled headers are turned on, you *must* have #include “stdafx.h” as the first include. Otherwise your includes don’t work.

    See this link for more info:
    http://en.wikipedia.org/wiki/Precompiled_header#stdafx.h

  • [...] this does yet, but just have faith and keep compiling’. It’s tricky to explain, but more info here if [...]

  • [...] have a simple program, which I copied exactly from the example in http://www.learncpp.com/cpp-tutorial/19-header-files/ because I’m learning how to make c++ programs with multiple [...]

  • ashik

    add.cpp must contain the “add.h” header, otherwise the declaration wont be found, happened to me

  • xconwing

    Yea, having a compile error as well. This is what I have in all three file.

    in main.cpp
    ////////////////////////
    #include
    #include “add.h” // this brings in the declaration for add()
    using namespace std;

    int main()
    {
    cout << "The sum of 3 and 4 is " << add(3,4) << endl;
    return 0;
    }

    in add.cpp
    ////////////////////////
    #include "add.h"

    int add(int x, int y)
    {
    return x+y;
    }

    in add.h
    ////////////////////////
    #ifndef ADD_H
    #define ADD_H

    int add(int x, int y); // function prototype for add.h

    #endif

    Btw, I’m working with CodeBlock compiler and the error is:
    undefined reference to ‘add(int, int)’

    thanks
    qL

  • [...] The C++ Premier I have doesn’t say much about what I am about to ask, and this is what I got googling LINK: [...]

  • Learner

    This is the best page so far! Ok, this is just the beggining of the tutorial, but it explains things I always had curiosity about: “Why to use header files?”, “Why the standard library is precompiled?”, “Why standard header files don’t end in .h?”. I appreciate very much how the topics are ordered and how the author answers all my doubts.

    • Why use header files – When you have 10k or more lines of code having it in one file is a royal pain. You use header files to split code between multiple files helping in both project management and code readability.
      Why is the standard library precompiled – The standard libs are large. Thousands of lines of code large. You do not want to recompile it every time you want to see whether your program works. That’s why they’re precompiled.
      Why standard header files don’t have the .h extension – some do. .h extension is useless and only wastes your time when you have to write it.

  • roy17

    hi
    i been trying to create a .h file and .cpp file
    i was able to use these two file as the header in the same project where i have saved both .cpp and .h file
    but i was not able to use in the different project
    it shows a message “file not found”
    by the way i am using Xcode

    when i use
    # include
    # include “GradeBook.h”
    using namespace std;
    int main ()
    {
    GradeBook gradeBook(“CS101 Introduction to C++ Programming”);
    GradeBook gradeBook1(“CS102 Introduction to C++ Programming”);
    cout<< "gradeBook created for course:"<<gradeBook.getCourseName()<<"\n gradeBook1 creaded for course:"<<gradeBook1.getCourseName()<<endl;

    return 0;

    }

    in the same project where i have .h file

    #ifndef practice_of_the_header_GradeBook_h
    #define practice_of_the_header_GradeBook_h
    # include

    using namespace std;

    class GradeBook
    {
    public:
    // provide all the member function protype
    GradeBook (string);// this is a consturctor
    void setCourseName(string);
    string getCourseName();
    void displayMessage();

    private:
    string CourseName;

    };// the class of the Gra

    #endif

    and .cpp flie

    # include
    # include
    #include “GradeBook.h”
    using namespace std;
    // constructor initialixes course Name with string supplies as argument
    GradeBook::GradeBook(string name)
    {
    setCourseName(name);

    }
    // function to set the course name
    void GradeBook::setCourseName(string name)
    {
    CourseName=name;
    }
    string GradeBook:: getCourseName()
    {
    return CourseName;

    }
    void GradeBook::displayMessage()
    {
    cout<<"Welcome to the grade book \n"<<getCourseName()<<"!"<<endl;
    }

    i worked fine

    but when i created a new project
    and try to use the same header it says file not found

    # include
    # include “GradeBook.h” !GradeBook.h file not found
    using namespace std;
    int main ()
    {
    GradeBook gradeBook(“CS101 Introduction to C++ Programming”);
    GradeBook gradeBook1(“CS102 Introduction to C++ Programming”); cout<< "gradeBook created for course:"<<gradeBook.getCourseName()<<"\n gradeBook1 creaded for course:"<<gradeBook1.getCourseName()<<endl;

    return 0;

    }

    can any one help me
    thanks

  • [...] Now, when the compiler is compiling main.cpp, it will know what add is. Using this method, we can give files access to functions that live in another file. However, as programs grow larger and larger, it becomes tedious to have to forward declare every function you use that lives in a different file. To solve that problem, the concept of header files was introduced. We discuss header files in the lesson on header files. [...]

  • [...] the lesson on header files, you learned that you can put functions inside header files in order to reuse them in multiple [...]

  • lopata

    Now, i am mad with this tutorial.

    1st of all, please explaing with SIMPLE words what is this line suppose to do.

    #ifndef ADD_H
    #define ADD_H // Command to define header

    int add(int x, int y); // function prototype for add.h // definition

    #endif // end of defining.

    In my understanding this should create a header add.h and define it ? right or wrong.
    If I want to do it manually, I can create add.h and define it my self, so above stated example has no common sense in this world.
    Defined add.h can look like this

    add.h
    int add(int x, int y); // function prototype for add.h // definition
    right or wrong?

  • fantastic source code!hi every body!

  • lilith

    Now I have created the header file and still get the same error:

    main.o: In function `main’:
    main.cpp:(.text+0×14): undefined reference to `add(int, int)’
    collect2: error: ld returned 1 exit status

    The compiler doesn’t find the add() function, neither with forward declaration nor using a header file. My code is an exact copy of your example and split in 3 files, main.cpp, add.cpp and add.h. Also, I have put all three files in the same directory, it contains only those three and nothing else.
    Where am I going wrong?

    • lilith

      Ok, I’ve solved my problem myself. It didn’t have anything to do with the example code, but simply with my lack of knowledge of g++.

      For any of you running into the same problem:
      %%%%%%%%%%%%%%%%%%%%
      g++ -c main.cpp
      g++ -c Complex.cpp
      g++ main.o Complex.o
      %%%%%%%%%%%%%%%%%%%
      This does the trick. Next, if you check the contents of your source file, you see an executable named “a.out”, which you have to call (“./a.out”) to run your code.
      Everything peachy now, I finally can move on with this very helpful tutorial!

  • TheElephant

    Keep in mind that header files typically only contain declarations. They do not define how something is implemented, and you already know that your program won’t link if it can’t find the implementation of something you use.

    #include
    #include “add.h” // this brings in the declaration for add()

    int main()
    {
    using namespace std;
    cout << "The sum of 3 and 4 is " << add(3, 4) << endl;
    return 0;
    }
    int add(int x, int y)
    {
    return x + y;
    }
    int add(int x, int y)
    {
    return x + y;
    }

  • TheElephant

    Keep in mind that header files typically only contain declarations. They do not define how something is implemented, and you already know that your program won’t link if it can’t find the implementation of something you use.

    #include
    #include “add.h” // this brings in the declaration for add()

    int main()
    {
    using namespace std;
    cout << "The sum of 3 and 4 is " << add(3, 4) << endl;
    return 0;
    }

    int add(int x, int y)
    {
    return x + y;
    }

  • rodrigor

    This is probably the most comprehensible C++ tutorial I have read. I’ve worked with the C++ language on and off for sometime now, and I’ve never found material has was able to explain the missing bit of information that I needed, such as the explanation behind #include <include> vs #include <include.h> which has been bothering me for years not to mention your C++11 section. Thank you for this amazing site.

  • [...] When to pass parameters by value, reference, and pointer. Headers and Includes: Why and [...]

  • [...] C++ did things compared to Delphi. That waste was mostly in the textual include mechanism used for header [...]

  • [...] the compiler. Use double quotes to include any other header files. Most compilers do it this way. http://www.learncpp.com/cpp-tutorial/19-header-files/ Explains in more detail about pre-processor directives. If you are a novice programmer, that page [...]

  • Ciprian

    Just AMAZING, this tutorial . .

You must be logged in to post a comment.