![\"vga](\"https:\/\/www.modernescpp.com\/wp-content\/uploads\/2019\/04\/vga-160266_1280.png\")
<\/p>\nToday, I complet the rules of the C++ core guidelines to source files. They are about header files and namespaces.<\/p>\n
<\/p>\n
<\/p>\n
<\/p>\n
Let’s see how I can make a story out of the remaining rules because they do have little content. Anyway, here are they:<\/p>\n
#include<\/code> guards for all .h<\/code> files<\/a><\/li>\n- SF.9: Avoid cyclic dependencies among source files<\/a><\/li>\n
- SF.10: Avoid dependencies on implicitly
#include<\/code>d names<\/a><\/li>\n- \n
SF.11: Header files should be self-contained<\/a><\/p>\n<\/li>\n- SF.20: Use
namespace<\/code>s to express logical structure<\/a><\/li>\n- SF.21: Don\u2019t use an unnamed (anonymous) namespace in a header<\/a><\/li>\n
- SF.22: Use an unnamed (anonymous) namespace for all internal\/nonexported entities<\/a><\/li>\n<\/ul>\n
The first rule is already best practice.<\/p>\n
SF.8: Use #include<\/code> guards for all .h<\/code> files<\/a><\/h2>\nWhen you put an include guard around your header file, it is only included once. Here is a small example from the guidelines.<\/p>\n
\n\/\/ file foobar.h:<\/span>\r\n#ifndef LIBRARY_FOOBAR_H<\/span>\r\n#define LIBRARY_FOOBAR_H<\/span>\r\n\/\/ ... declarations ...<\/span>\r\n#endif <\/span>\/\/ LIBRARY_FOOBAR_H<\/span>\r\n<\/pre>\n<\/div>\n <\/p>\n
There are two points to keep in mind.<\/p>\n
\n- Give your guard a unique name. If you use a guard name more than once, it may exclude the inclusion of a header file.<\/li>\n
- #pragma once<\/a> is a non-standard but widely supported preprocessor directive. This means the following variation of the header foobar.h<\/span> is not portable.<\/li>\n<\/ol>\n\n
\/\/ file foobar.h:<\/span>\r\n#pragma once<\/span>\r\n\r\n\/\/ ... declarations ...<\/span>\r\n<\/pre>\n<\/div>\n <\/p>\n
For example, GCC has supported the preprocessor directive since 3.4. Read the details about the #pragma once<\/a> supported in the Wikipedia article.<\/p>\nOkay, the following rule is tricky.<\/p>\n<\/p>\n
SF.9: Avoid cyclic dependencies among source files<\/a><\/h2>\nFirst of all, what is a cyclic dependency of source files? Imagine, I have the following source files.<\/p>\n
\n- a.h<\/span><\/li>\n<\/ul>\n\n
#ifndef LIBRARY_A_H<\/span>\r\n#define LIBRARY_A_H<\/span>\r\n#include \"b.h\"<\/span>\r\n\r\nclass<\/span> A<\/span> {\r\n B<\/span> b;\r\n};\r\n\r\n#endif <\/span>\/\/ LIBRARY_A_H<\/span>\r\n<\/pre>\n<\/div>\n\n- b.h<\/span><\/li>\n<\/ul>\n\n
#ifndef LIBRARY_B_H<\/span>\r\n#define LIBRARY_B_H<\/span>\r\n#include \"a.h\"<\/span>\r\n\r\nclass<\/span> B<\/span> {\r\n A a;\r\n};\r\n\r\n#endif <\/span>\/\/ LIBRARY_B_H<\/span>\r\n<\/pre>\n<\/div>\n\n- main.cpp<\/span><\/li>\n<\/ul>\n\n
#include \"a.h\"<\/span><\/span>\r\n\r\nint<\/span> main<\/span>() {\r\n A a;\r\n}\r\n<\/pre>\n<\/div>\n <\/p>\n
When I try to compile the program, it fails:![\"dependency\"](\"https:\/\/www.modernescpp.com\/wp-content\/uploads\/2016\/07\/dependency.png\")
<\/p>\n
The issue is a circular dependency between the headers a.h<\/span> and b.h<\/span>. The problem manifests itself when a<\/span> is created in the main program. To create an A, the compiler must figure out the size of B<\/span>. To create a B<\/span>, the compiler must figure out the size of A<\/span>. This is not possible if a<\/span> or b<\/span> are objects. It is only possible if a<\/span> or b<\/span> are pointers or references.<\/p>\nThe easy fix is, therefore, to forward declare<\/a> A<\/span> in b.h<\/span> or B<\/span> in a.h<\/span>. Depending on your platform, the size is now 32 or 64 bits. Here is the modified header of a.h<\/span>.<\/p>\n <\/p>\n
\n#ifndef LIBRARY_A_H<\/span>\r\n#define LIBRARY_A_H<\/span>\r\n\r\nclass<\/span> B<\/span>;\r\n\r\nclass<\/span> A<\/span> {\r\n B*<\/span> b;\r\n B&<\/span> b2 =<\/span> *<\/span>b;\r\n};\r\n\r\n#endif <\/span>\/\/ LIBRARY_A_H<\/span>\r\n<\/pre>\n<\/div>\n <\/p>\n
By the way, the standard library header <iosfwd><\/span><\/a> holds forward input\/output library declarations.<\/p>\nThe next issue happened to me a few times.<\/p>\n
SF.10: Avoid dependencies on implicitly #include<\/code>d names<\/a><\/h2>\nFor example, the following program will compile with GCC 5.4 but break with the Microsoft compiler 19.00.23506.<\/p>\n
\n#include <iostream><\/span>\r\n\r\nint<\/span> main<\/span>(){\r\n \r\n std::<\/span>string s =<\/span> \"Hello World\"<\/span>;\r\n std::<\/span>cout <<<\/span> s;\r\n\r\n}\r\n <\/pre>\n<\/div>\n <\/p>\n
I forgot to include a necessary header <string><\/span>. GCC 5.4 includes <string><\/span> with the header <iostream>. <\/span>This does not hold true for the Microsoft compiler. The error message of the Microsoft compiler is quite verbose.<\/p>\n ![\"forgotString\"](\"https:\/\/www.modernescpp.com\/wp-content\/uploads\/2019\/04\/forgotString.png\")
<\/p>\n
The following rule is short but essential.<\/p>\n
SF.11: Header files should be self-contained<\/a><\/h2>\nA self-contained header file can be included top-most<\/em> 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.<\/p>\nThe last three rules to source files are about namespaces. It starts with a no-brainer.<\/p>\n
SF.20: Use namespace<\/code>s to express logical structure<\/a><\/h2>\nObviously, we have namespaces in the C++ standard to express logical structure. Examples? Here are a few:<\/p>\n
\nstd\r\nstd::<\/span>chrono\r\nstd::<\/span>literals
std::literals::chrono_literals\r\nstd::<\/span>filesystem
std::placeholders\r\n\r\nstd::<\/span>view \/\/ C++20<\/span>\r\n<\/pre>\n<\/div>\n <\/p>\n
The next two rules are about unnamed (anonymous) namespaces.<\/p>\n
SF.21: Don\u2019t use an unnamed (anonymous) namespace in a header, <\/a>and SF.22: Use an unnamed (anonymous) namespace for all internal\/nonexported entities<\/a><\/h2>\nAn 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<\/a>). The same holds for namespaces, which are declared in the unnamed namespace. Okay, what does that mean?<\/p>\n\nnamespace<\/span> {\r\n int i<\/span>; \/\/ defines ::(unique_name)::i<\/span>\r\n}\r\nvoid<\/span> inc() {\r\n i++<\/span>; \/\/ increments ::(unique_name)::i<\/span>\r\n}\r\n \r\n<\/pre>\n<\/div>\n <\/p>\n
When you refer to I from within the translation unit, you do it by a unique_name <\/span>without a name clash. For example, you can define a free addition function add<\/span> inside the unnamed namespace, and the linker would not complain because you broke the one definition rule.<\/p>\nAnd here is the problem, when you use an unnamed namespace in the header (SF21<\/a>). Each translation unit will define its unique instance of the unnamed namespace. Unnamed namespaces in headers have a few consequences:<\/p>\n\n- The resulting executable will bloat.<\/li>\n
- Any declaration in an unnamed namespace refers to a different entity in each translation unit. This may not be the expected behavior.<\/li>\n<\/ul>\n
The usage of an unnamed namespace is similar to the static<\/span> keyword used in C.<\/p>\n\nnamespace<\/span> { int<\/span> i1; }\r\nstatic<\/span> int<\/span> i2;\r\n<\/pre>\n<\/div>\n <\/p>\n
What’s next?<\/h2>\n