C++ Core Guidelines: The Remaining Rules to Source Files

Today, I complete the rules of the C++ core guidelines to source files. They are about header files and namespaces.

 

vga 160266 1280

Let's see how I can make a story out of the remaining rules because they have not much content. Anyway, here are they:

The first rule is already best practice.

SF.8: Use #include guards for all .h files

When you put an include guard around your header file, it is only be included once. Here is a small example from the guidelines.

// file foobar.h:
#ifndef LIBRARY_FOOBAR_H
#define LIBRARY_FOOBAR_H
// ... declarations ...
#endif // LIBRARY_FOOBAR_H

There are two points to keep in mind.

  1. Give your guard a unique name. If you use a guard name more than once, it may exclude the inclusion of a header file.
  2. #pragma once is non-standard but widely supported preprocessor directive. This means, the following variation of the header foobar.h is not portable.
// file foobar.h:
#pragma once

// ... declarations ...

For example, GCC supports the preprocessor directive since 3.4. Read the details about the #pragma once support in the Wikipedia article.

Okay, the next rule is tricky.

SF.9: Avoid cyclic dependencies among source files

First of all, what is a cyclic dependency of source files? Imagine, I have the following source files.

  •  a.h
#ifndef LIBRARY_A_H
#define LIBRARY_A_H
#include "b.h"

class A {
  B b;
};

#endif // LIBRARY_A_H
  • b.h
#ifndef LIBRARY_B_H
#define LIBRARY_B_H
#include "a.h"

class B {
  A a;
};

#endif // LIBRARY_B_H
  • main.cpp
#include "a.h"

int main() {
  A a;
}

When I try to compile the program, it will fail:dependency

The issue is that there is a circular dependency between the headers a.h and b.h. The problem manifests itself when a is created in the main program. To create an A, the compiler must figure out the size of B. To create a B, the compiler must figure out the size of A. This is not possible if a or b are objects. It is only possible if a or b are pointers or references.

The easy fix is, therefore, to forward declare A in b.h or B in a.h. Depending on your platform, the size is now 32 or 64 bits.  Here is the modified header of a.h.

 

#ifndef LIBRARY_A_H
#define LIBRARY_A_H

class B;

class A {
  B* b;
  B& b2 = *b;
};

#endif // LIBRARY_A_H

 

By the way, the standard library header <iosfwd> holds forward declarations of the input/output library.

The next issue happens to me a few times.

SF.10: Avoid dependencies on implicitly #included names

For example, the following program will compile with GCC 5.4 but will break with the Microsoft compiler 19.00.23506.

#include <iostream>

int main(){
    
    std::string s = "Hello World";
    std::cout << s;

}
 

 

I forgot to include a necessary header <string>. GCC 5.4 includes <string> with the header <iostream>. This does not hold true for the Microsoft compiler. The error message of the Microsoft compiler is quite verbose.

 forgotString

The next rule is short but important.

SF.11: Header files should be self-contained

A self-contained header file can be included top-most in a translation unit. This means it does not depend on other headers that are included before. If you don't follow this rule, a user of your header may be surprised by difficult to understand error messages. Sometimes the header seems to work; sometimes not. It just depends on which header was included before.

The last three rules to source files are about namespaces. It starts with a no-brainer.

SF.20: Use namespaces to express logical structure

Obviously, we have namespaces in the C++ standard to express logical structure. Examples? Here are a few:

std
std::chrono
std::literals
std::literals::chrono_literals std::filesystem
std::placeholders std::view // C++20

 

The next two rules are about unnamed (anonymous) namespaces.

SF.21: Don’t use an unnamed (anonymous) namespace in a header and SF.22: Use an unnamed (anonymous) namespace for all internal/nonexported entities

An unnamed namespace has internal linkage. This means, that names inside the unnamed namespace can only be referred from within the current translation unit and are not exported (SF22). The same holds for namespaces, which are declared in the unnamed namespace. Okay, what does that mean?

namespace {
    int i;  // defines ::(unique_name)::i
}
void inc() {
    i++;  // increments ::(unique_name)::i
}
 

When you refer to i from within the translation unit, you do it by a unique_name without a name clash. For example, you can define a free addition function add inside the unnamed namespace, and the linker would not complain because you broke the one definition rule.

And here is the problem, when you use an unnamed namespace in the header (SF21). Each translation unit will define its unique instance of the unnamed namespace. Unnamed namespaces in headers have a few consequences:

  • The resulting executable will bloat.
  • Any declaration in an unnamed namespace refers to a different entity in each translation unit. This may not be the expected behaviour.

The usage of an unnamed namespace is similar to the static keyword used in C.

namespace { int i1; }
static int i2;

What's next?

The C++ core guidelines mentioned a few times modules in the rules to source files, but they didn't write about the big C++20 feature. Let me fill the gap in my next post.

 

 

Thanks a lot to my Patreon Supporters: Paul Baxter,  Meeting C++, Matt Braun, Avi Lachmish, Roman Post anciuc, Venkata Ramesh Gudpati, Tobias Zindl, Dilettant, Marko, Ramesh Jangama, G Prvulovic, Reiner Eiteljörge, Benjamin Huth, Reinhold Dröge, Timo, Abernitzke, Richard Ohnemus , Frank Grimm, and Hasan Men.

Thanks in particular to:  TakeUpCode 450 60     crp4

 

Get your e-book at Leanpub:

The C++ Standard Library

 

Concurrency With Modern C++

 

Get Both as one Bundle

cover   ConcurrencyCoverFrame   bundle
With C++11, C++14, and C++17 we got a lot of new C++ libraries. In addition, the existing ones are greatly improved. The key idea of my book is to give you the necessary information to the current C++ libraries in about 200 pages.  

C++11 is the first C++ standard that deals with concurrency. The story goes on with C++17 and will continue with C++20.

I'll give you a detailed insight in the current and the upcoming concurrency in C++. This insight includes the theory and a lot of practice with more the 100 source files.

 

Get my books "The C++ Standard Library" (including C++17) and "Concurrency with Modern C++" in a bundle.

In sum, you get more than 600 pages full of modern C++ and more than 100 source files presenting concurrency in practice.

 

Get your interactive course

 

Modern C++ Concurrency in Practice

C++ Standard Library including C++14 & C++17

educative CLibrary

Based on my book "Concurrency with Modern C++" educative.io created an interactive course.

What's Inside?

  • 140 lessons
  • 110 code playgrounds => Runs in the browser
  • 78 code snippets
  • 55 illustrations

Based on my book "The C++ Standard Library" educative.io created an interactive course.

What's Inside?

  • 149 lessons
  • 111 code playgrounds => Runs in the browser
  • 164 code snippets
  • 25 illustrations

Cranepay

Add comment


Subscribe to the newsletter (+ pdf bundle)

Blog archive

Source Code

Visitors

Today 2340

All 2041743

Currently are 94 guests and no members online

Kubik-Rubik Joomla! Extensions

Latest comments