vga 160266 1280

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

Today, I complet 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 do have little 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 included once. Here is a small example from the guidelines.

 

Rainer D 6 P2 500x500Modernes C++ Mentoring

Be part of my mentoring programs:

  • "Fundamentals for C++ Professionals" (open)
  • "Design Patterns and Architectural Patterns with C++" (open)
  • "C++20: Get the Details" (open)
  • "Concurrency with Modern C++" (starts March 2024)
  • Do you want to stay informed: Subscribe.

     

    // 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 a 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 has supported the preprocessor directive since 3.4. Read the details about the #pragma once supported in the Wikipedia article.

    Okay, the following 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 fails:dependency

    The issue 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 input/output library declarations.

    The next issue happened 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 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 following rule is short but essential.

    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 behavior.

    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 modules in the rules to source files a few times, 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: Matt Braun, Roman Postanciuc, Tobias Zindl, G Prvulovic, Reinhold Dröge, Abernitzke, Frank Grimm, Sakib, Broeserl, António Pina, Sergey Agafyin, Андрей Бурмистров, Jake, GS, Lawton Shoemake, Jozo Leko, John Breland, Venkat Nandam, Jose Francisco, Douglas Tinkham, Kuchlong Kuchlong, Robert Blanch, Truels Wissneth, Kris Kafka, Mario Luoni, Friedrich Huber, lennonli, Pramod Tikare Muralidhara, Peter Ware, Daniel Hufschläger, Alessandro Pezzato, Bob Perry, Satish Vangipuram, Andi Ireland, Richard Ohnemus, Michael Dunsky, Leo Goodstadt, John Wiederhirn, Yacob Cohen-Arazi, Florian Tischler, Robin Furness, Michael Young, Holger Detering, Bernd Mühlhaus, Stephen Kelley, Kyle Dean, Tusar Palauri, Dmitry Farberov, Juan Dent, George Liao, Daniel Ceperley, Jon T Hess, Stephen Totten, Wolfgang Fütterer, Matthias Grün, Phillip Diekmann, Ben Atakora, Ann Shatoff, Rob North, Bhavith C Achar, Marco Parri Empoli, moon, Philipp Lenk, Hobsbawm, and Charles-Jianye Chen.

    Thanks, in particular, to Jon Hess, Lakshman, Christian Wittenhorst, Sherhy Pyton, Dendi Suhubdy, Sudhakar Belagurusamy, Richard Sargeant, Rusty Fleming, John Nebel, Mipko, Alicja Kaminska, Slavko Radman, and David Poole.

    My special thanks to Embarcadero
    My special thanks to PVS-Studio
    My special thanks to Tipi.build 
    My special thanks to Take Up Code
    My special thanks to SHAVEDYAKS

    Seminars

    I’m happy to give online seminars or face-to-face seminars worldwide. Please call me if you have any questions.

    Standard Seminars (English/German)

    Here is a compilation of my standard seminars. These seminars are only meant to give you a first orientation.

    • C++ – The Core Language
    • C++ – The Standard Library
    • C++ – Compact
    • C++11 and C++14
    • Concurrency with Modern C++
    • Design Pattern and Architectural Pattern with C++
    • Embedded Programming with Modern C++
    • Generic Programming (Templates) with C++
    • Clean Code with Modern C++
    • C++20

    Online Seminars (German)

    Contact Me

    Modernes C++ Mentoring,

     

     

    0 replies

    Leave a Reply

    Want to join the discussion?
    Feel free to contribute!

    Leave a Reply

    Your email address will not be published. Required fields are marked *