c++ files - Including#includes in header file vs source file




function definition (2)

I like to put all my #includes in my header file then only include my header for that source file in my source file. What is the industry standard? Are there any draw backs to my method?


Answers

Generally, you only want to put the minimum necessary includes into a class header file, as anyone else who uses that header will be forced to #include all of them too. In larger projects, this leads towards slower builds, dependency issues, and all sorts of other nastiness.

Think of a header file as the public interface to your class. You don't want to saddle everyone who uses it with extra dependencies, unless they're necessary to be able to use the class.

Move anything that's only needed in the class implementation down into the source file. For other classes used in a header, only #include their headers if you actually need to know their size or contents in the header - anything else and a forward declaration is sufficient. Most cases, you only need to #include classes you're inheriting from, and classes whose objects are value members of your class.

This page has a good summary. (Replicated below for reference)


C++ Header File Include Patterns #

Large software projects require a careful header file management even when programming in C. When developers move to C++, header file management becomes even more complex and time consuming. Here we present a few header file inclusion patterns that will simplify this chore.

Header File Inclusion Rules

Here, we discuss the basic rules of C++ header file inclusion needed to simplify header file management.

A header file should be included only when a forward declaration would not do the job. The header file should be so designed that the order of header file inclusion is not important. This is achieved by making sure that x.h is the first header file in x.cpp The header file inclusion mechanism should be tolerant to duplicate header file inclusions. The following sections will explain these rules with the help of an example.

Header File Inclusion Example

The following example illustrates different types of dependencies. Assume a class A with code stored in a.cpp and a.h.

a.h

#ifndef _a_h_included_
#define _a_h_included_
#include "abase.h"
#include "b.h"

// Forward Declarations
class C;
class D;

class A : public ABase
{
  B m_b;
  C *m_c;
  D *m_d;

public:
  void SetC(C *c);
  C *GetC() const;

  void ModifyD(D *d);
};
#endif

a.cpp

#include "a.h"
#include "d.h"

void A::SetC(C* c)
{
  m_c = c;
}

C* A::GetC() const
{
  return m_c;
}

void A::ModifyD(D* d)
{
  d->SetX(0);
  d->SetY(0);
  m_d = d;
}

File Inclusion Analysis

Lets analyze the header file inclusions, from the point of view of classes involved in this example, i.e. ABase, A, B, C and D.

  • Class ABase: ABase is the base class, so the class declaration is required to complete the class declaration. The compiler needs to know the size of ABase to determine the total size of A. In this case abase.h should be included explicitly in a.h.
  • Class B: Class A contains Class B by value , so the class declaration is required to complete the class declaration. The compiler needs to know the size of B to determine the total size of A. In this case b.h should be included explicitly in a.h.
  • Class C: Class C is included only as a pointer reference. The size or actual content of C are not important to a.h or a.cpp. Thus only a forward declaration has been included in a.h. Notice that c.h has not been included in either a.h or a.cpp.
  • Class D: Class D is just used as a pointer reference in a.h. Thus a forward declaration is sufficient. But a.cpp uses class D in substance so it explicitly includes d.h.

Key Points

Header files should be included only when a forward declaration will not do the job. By not including c.h and d.h other clients of class A never have to worry about c.h and d.h unless they use class C and D by value. a.h has been included as the first header file in a.cpp This will make sure that a.h does not expect a certain header files to be included before a.h. As a.h has been included as the first file, successful compilation of a.cpp will ensure that a.h does not expect any other header file to be included before a.h. If this is followed for all classes, (i.e. x.cpp always includes x.h as the first header) there will be no dependency on header file inclusion. a.h includes the check on preprocessor definition of symbol _a_h_included_. This makes it tolerant to duplicate inclusions of a.h.

Cyclic Dependency

Cyclic dependency exists between class X and Y in the following example. This dependency is handled by using forward declarations.

x.h and y.h

/* ====== x.h ====== */
// Forward declaration of Y for cyclic dependency
class Y;

class X 
{
    Y *m_y;
    ...
};

/* ====== y.h ====== */
// Forward declaration of X for cyclic dependency
class X;

class Y 
{
    X *m_x;
    ...
};

I'd suggest reading the W3 wiki page about structuring HTML5:

<header> Used to contain the header content of a site. <footer> Contains the footer content of a site. <nav> Contains the navigation menu, or other navigation functionality for the page.

<article> Contains a standalone piece of content that would make
sense if syndicated as an RSS item, for example a news item.

<section> Used to either group different articles into different
purposes or subjects, or to define the different sections of a single article.

<aside> Defines a block of content that is related to the main content around it, but not central to the flow of it.

They include an image that I've cleaned up here:

In code, this looks like so:

<body>
  <header></header>    
  <nav></nav>    
  <section id="sidebar"></section>    
  <section id="content"></section>    
  <aside></aside>    
  <footer></footer>
</body>

Let's explore some of the HTML5 elements in more detail.

<section>

The <section> element is for containing distinct different areas of functionality or subjects area, or breaking an article or story up into different sections. So in this case: "sidebar1" contains various useful links that will persist on every page of the site, such as "subscribe to RSS" and "Buy music from store". "main" contains the main content of this page, which is blog posts. On other pages of the site, this content will change. It is a fairly generic element, but still has way more semantic meaning than the plain old <div>.

<article>

<article> is related to <section>, but is distinctly different. Whereas <section> is for grouping distinct sections of content or functionality, <article> is for containing related individual standalone pieces of content, such as individual blog posts, videos, images or news items. Think of it this way - if you have a number of items of content, each of which would be suitable for reading on their own, and would make sense to syndicate as separate items in an RSS feed, then <article> is suitable for marking them up. In our example, <section id="main"> contains blog entries. Each blog entry would be suitable for syndicating as an item in an RSS feed, and would make sense when read on its own, out of context, therefore <article> is perfect for them:

<section id="main">
    <article><!-- first blog post --></article>        
    <article><!-- second blog post --></article>        
    <article><!-- third blog post --></article>
</section>

Simple huh? Be aware though that you can also nest sections inside articles, where it makes sense to do so. For example, if each one of these blog posts has a consistent structure of distinct sections, then you could put sections inside your articles as well. It could look something like this:

<article>
  <section id="introduction"></section>      
  <section id="content"></section>
  <section id="summary"></section>
</article>

<header> and <footer>

as we already mentioned above, the purpose of the <header> and <footer> elements is to wrap header and footer content, respectively. In our particular example the <header> element contains a logo image, and the <footer> element contains a copyright notice, but you could add more elaborate content if you wished. Also note that you can have more than one header and footer on each page - as well as the top level header and footer we have just discussed, you could also have a <header> and <footer> element nested inside each <article>, in which case they would just apply to that particular article. Adding to our above example:

<article>
  <header></header>    
  <section id="introduction"></section>      
  <section id="content"></section>      
  <section id="summary"></section>      
  <footer></footer>
</article>

<nav>

The <nav> element is for marking up the navigation links or other constructs (eg a search form) that will take you to different pages of the current site, or different areas of the current page. Other links, such as sponsored links, do not count. You can of course include headings and other structuring elements inside the <nav>, but it's not compulsory.

<aside>

you may have noticed that we used an <aside> element to markup the 2nd sidebar: the one containing latest gigs and contact details. This is perfectly appropriate, as <aside> is for marking up pieces of information that are related to the main flow, but don't fit in to it directly. And the main content in this case is all about the band! Other good choices for an <aside> would be information about the author of the blog post(s), a band biography, or a band discography with links to buy their albums.

Where does that leave <div>?

So, with all these great new elements to use on our pages, the days of the humble <div> are numbered, surely? NO. In fact, the <div> still has a perfectly valid use. You should use it when there is no other more suitable element available for grouping an area of content, which will often be when you are purely using an element to group content together for styling/visual purposes. A common example is using a <div> to wrap all of the content on the page, and then using CSS to centre all the content in the browser window, or apply a specific background image to the whole content.





c++ file header include