CppHeaderFile.md

(C++) Header file

Header files contain the declarations of functions and classes.

Header files commonly have the .h and .hpp filename extensions.

To use a header file, it must be #included in the source code.

#include <iostream>
#include "Widget.h"
 
int main()
{
  Widget w;
  std::cout << "Hello world\n";
}

A header (.h) file can (and commonly does) start with an #include guard. The combination of a header (.h) file and an implementation (.cpp) file is called a unit.

Examples

This example is copied from [17].

//radio.h
#ifndef INCLUDED_RADIO
#define INCLUDED_RADIO

int z;                              // illegal: external data definition
extern int LENGTH = 10;             // illegal: external data definition
const int WIDTH = 5;                // avoid: constant data definition
static int y;                       // avoid: static data definition
static void func() {/*...*/}        // avoid: static function definition

class Radio
{
    static int s_count;             // fine: static member declaration
    static const double S_PI;       // fine: static const member declaration
    int d_size;                     // fine: member data definition
    // ...
  public:
    int size() const;               // fine: member function declaration
    // ...
};                                  // fine: class definition

inline int Radio::size() const
{
    return d_size;
}                                   // fine: inline function definition

int Radio::s_count;                 // illegal: static member definition

double Radio::S_PI = 3.14159265358; // illegal: static const member definition

int Radio::size() const { /*...*/ } // illegal: member function definition

#endif // INCLUDED_RADIO

Standard header files

The STL consists out of the following header files [3][4]:

1. algorithm
2. array
3. atomic
4. bitset
5. cassert
6. ccomplex
7. cctype
8. cerrno
9. cfenv
10. cfloat
11. chrono
12. cinttypes
13. ciso646
14. climits
15. clocale
16. cmath
17. codecvt
18. complex
19. condition_variable
20. csetjmp
21. csignal
22. cstdalign
23. cstdarg
24. cstdbool
25. cstddef
26. cstdint
27. cstdio
28. cstlib
29. cstring
30. ctime
31. complex
32. ctgmath
33. ctime
34. cuchar
35. cwchar
36. cwctype
37. deque
38. exception
39. forward_list
40. fstream
41. functional
42. future
43. initializer_list
44. iomanip
45. ios
46. iosfwd
47. iostream
48. istream
49. iterator
50. limits
51. list
52. locale
53. map
54. memory
55. mutex
56. new
57. numeric
58. ostream
59. queue
60. random
61. ratio
62. regex
63. set
64. sstream
65. stack
66. stdexcept
67. streambuf
68. string
69. strstream
70. system_error
71. thread
72. tuple
73. typeindex
74. typeinfo
75. type_traits
76. utility
77. valarray
78. vector
79. unordered_map
80. unordered_set

Advice

• Make header files self-sufficient [1,14]
• Don't put a using-directive in a header file [18,19]
• Avoid non-inline function definitions in header files [7,9,12]
• #include C header files in namespace to avoid global names [13]. For example, #include cmath instead of math.h
• include user-defined headers' names in quotes, include STL headers' names in angle brackets [15]
• Short functions should be inlined and defined in headers [16]
• Large functions should be declared in headers and defined in source files [16]

References

1. Herb Sutter, Andrei Alexandrescu. C++ coding standards: 101 rules, guidelines, and best practices. 2005. ISBN: 0-32-111358-6. Item 23: 'Make header files self-sufficient'.
2. Herb Sutter, Andrei Alexandrescu. C++ coding standards: 101 rules, guidelines, and best practices. 2005. ISBN: 0-32-111358-6. Item 24: 'Always write interal #include guards. Never write external #include guards'.
3. International C++ Standard, table 11
4. Draft of C++0x Standard, table 14 and 15, ISO/IEC JTC1 SC22 WG21 N 3290, Date: 2011-04-11, ISO/IEC FDIS 14882, ISO/IEC JTC1 SC22
5. John Lakos. Large-Scale C++ Software Design. 1996. ISBN: 0-201-63362-0. Chapter 1.1.3, figure 1-3, page 28
6. John Lakos. Large-Scale C++ Software Design. 1996. ISBN: 0-201-63362-0. Section D.2: Major Design Rules, Chapter 2, page 820: 'Avoid free functions (except operator functions) at file scope in .h files'
7. Bjarne Stroustrup. The C++ Programming Language (3rd edition). 1997. ISBN: 0-201-88954-4. Section 9.5, item 4: 'Avoid non-inline function definitions in headers'
8. John Lakos. Large-Scale C++ Software Design. 1996. ISBN: 0-201-63362-0. Section 2.5, page 85: 'Place a redundant (external) include guard around each preprocessor include directive in every header file'
9. Joint Strike Fighter Air Vehicle C++ Coding Standards for the System Development and Demonstration Program. Document Number 2RDU00001 Rev C. December 2005. AV Rule 39: 'Header files (*.h) will not contain non-const variable definitions or function definitions.'
10. Bjarne Stroustrup. The C++ Programming Language (4th edition). 2013. ISBN: 978-0-321-56384-2. Chapter 15.5. Advice. page 444: '[1] Use header files to represent interfaces and to emphasize logical structure'
11. Bjarne Stroustrup. The C++ Programming Language (4th edition). 2013. ISBN: 978-0-321-56384-2. Chapter 15.5. Advice. page 444: '[2] #include a header in the source file that implements its functions'
12. Bjarne Stroustrup. The C++ Programming Language (4th edition). 2013. ISBN: 978-0-321-56384-2. Chapter 15.5. Advice. page 444: '[4] Avoid non-inline function definitions in headers'
13. Bjarne Stroustrup. The C++ Programming Language (4th edition). 2013. ISBN: 978-0-321-56384-2. Chapter 15.5. Advice. page 444: '[8] #include C headers in namespace to avoid global names'
14. Bjarne Stroustrup. The C++ Programming Language (4th edition). 2013. ISBN: 978-0-321-56384-2. Chapter 15.5. Advice. page 444: '[9] Make headers self-contained'
15. Paul Deitel, Harvey Deitel. C++11 for programmers (2nd edition). 2014. ISBN: 978-0-13-343985-4. Chapter 3.6, Error-Prevention Tip 3.3. page 57: 'To ensure that the preprocessor can locate headers correctly, #include preprocessing directives should place user-defined headers names in quotes [...] and place C++ Standard Library headers names in angle brackets [...]'
16. Gottschling, Peter. Discovering Modern C++: An Intensive Course for Scientists, Engineers, and Programmers. Addison-Wesley Professional, 2015. Chapter 7.2.3.2: 'Short functions should be inline and defined in headers. Large functions should be declared in headers and defined in source files'
17. John Lakos. Large-Scale C++ Software Design. 1996. ISBN: 0-201-63362-0. Chapter 1.1.3, Figure 1-3, page 28
18. Bjarne Stroustrup. The C++ Programming Language (4th edition). 2013. ISBN: 978-0-321-56384-2. Chapter 14.5. Advice. page 417: '[11] Don't put a using-directive in a header file'
19. Herb Sutter, Andrei Alexandrescu. C++ coding standards: 101 rules, guidelines, and best practices. 2005. ISBN: 0-32-111358-6. Item 59: 'Don't write namespace usings in a header file or before an #include'