What are common bad practices beginners make with C++ header inclusions and file structures?

This article is meant to address a common newbie problem regarding failure to understand #include, headers, and source file interaction. Several good practices are outlined and explained to show how to avoid some ugly snags. 1) Why we need header files. (1) It speeds up compile time. (2) It keeps your code more organized (3) It allows you to separate interface from implementation. Those are the upsides, but the big, obvious downside is that is makes things a little more complicated if you don't understand how it all works. C++ programs are built in a two stage process. First, each source file is compiled on its own. The compiler generates intermediate files for each compiled source file. These intermediate files are often called object files -- but they are not to be confused with objects in your code. Once all the files have been individually compiled, it then links all the object files together, which generates the final binary (the program). This means that each source file is compiled separately from other source files. As a result of this, in terms of compiling, "a.cpp" is clueless as to what's going on inside of "b.cpp". Here's a quick example to illustrate: // in myclass.cpp class MyClass { public: void foo(); int bar; }; void MyClass::foo() { // do stuff } // in main.cpp int main() { MyClass a; // Compiler error: 'MyClass' is unidentified return 0; } Even though MyClass is declared in your program, it is not declared in main.cpp, and therefore when you compile main.cpp you get that error. This is where header files come in. Header files allow you to make the interface (in this case, the class MyClass) visible to other .cpp files, while keeping the implementation (in this case, MyClass's member function bodies) in its own .cpp file. That same example again, but tweaked slightly: // in myclass.h class MyClass { public: void foo(); int bar; }; // in myclass.cpp #include "myclass.h" void MyClass::foo() { } //in main.cpp #include "myclass.h" // defines MyClass int main() { MyClass a; // no longer produces an error, because MyClass is defined return 0; } The #include statement is basically like a copy/paste operation. The compiler will "replace" the #include line with the actual contents of the file you're including when it compiles the file. 2) What is the difference between .h/.cpp/.hpp/.cc/etc All files are fundamentally the same in that they're all text files, however different kinds of files should have different extensions: - Header files should use a .h__ extension (.h / .hpp / .hxx). Which of those you use doesn't matter. - C++ Source files should use a .c__ extention (.cpp / .cxx / .cc). Which of those you use doesn't matter. - C Source files should use .c (.c only). So what's the difference between Header files and Source files? Basically, header files are #included and not compiled, whereas source files are compiled and not #included. 3) The "right way" to include ** There are two basic kinds of dependencies you need to be aware of: 1) stuff that can be forward declared 2) stuff that needs to be #included If, for example, class A uses class B, then class B is one of class A's dependencies. Whether it can be forward declared or needs to be included depends on how B is used within A: - do nothing if: A makes no references at all to B - do nothing if: The only reference to B is in a friend declaration - forward declare B if: A contains a B pointer or reference: B* myb; - forward declare B if: one or more functions has a B object/pointer/reference as a parementer, or as a return type: B MyFunction(B myb); - #include "b.h" if: B is a parent class of A - #include "b.h" if: A contains a B object: B myb; read less