"Many things are not in-depth. I think I understand them, but when I really use them in the project, I find the problem. I thought I was familiar with writing C language, especially in the engineering management of software files, because I was confident in my coding style（ After all, when I first graduated, my boss trained me in the standardization of coding format)
I thought that a. C file corresponds to an. H file, and the. C file only contains its own. H file. If the contents of other files are used in the. C file, the. H file can include the header file used.
I seem to have been adhering to this idea in coding (terrible). When the number of project files is small, there seems to be no problem with this concept, but with the increasing number of project files, I find that my idea has disadvantages: header files contain each other, resulting in the assumption that some macro variables can work when they are declared during compilation, but the actual test shows that after coding in this way, some declared macros can not work.
After the correction of leaders and colleagues, I realized that the original coding habits were incorrect. The. H file corresponding to the. C file should only contain the header files of other files used in the header file, and any unnecessary. H file should not be included; The. C file contains all the. H files used. In this way, even if the header file in the. C file is repeated, it does not hurt the elegance.
Sometimes the language description is too abstract, but it is still symbolic. For example: if there are two. C files, a.c and B.C, naturally they all have their own A.H and B.H files.
Original ideas:
A. There is only one #include "A.H" in C, and A.H contains a lot, such as B.H, C.H, D.H. File, because the contents of B.H, C.H and D.H are used in a.c file. As shown in Figure 1.
New ideas:
A. H only contains the. H file used for the content written by A.H. most of the time, A.H does not need any. H file. In the A.C file, it should be written as #include "B.H" #include "C.H" #include "D.H". Moreover, the. C files of the two files can contain each other in the header file. As shown in Figure 2.
The header file encountered in the project contains problems, which led me to re search the data for an in-depth understanding of the problem. Therefore, the following is the sorting of relevant contents through the search of network resources and my own understanding of it, hoping to be helpful to interested partners.
background
For C language, the design of header file reflects most of the system design. Unreasonable header file layout is the root cause of long compilation time. Unreasonable header file is actually unreasonable design.
rely on
Specifically refers to compilation dependency. If x.h contains y.H, it is called X dependent y. Dependencies are conducted. For example, if x.h contains y.H and y.H contains z.h, then x depends on Z through y. Dependency will lead to an increase in compilation time.
Although dependency is inevitable and necessary, poor design will lead to extremely complex dependencies of the whole system, making the modification of any file have to recompile the whole system, resulting in a huge increase in compilation time.
In a well-designed system, to modify a file, you only need to recompile several, or even one file.
A product once conducted an experiment to annotate the implementation of all functions through tools, and its compilation time was reduced by less than 10%. The reason is that a contains B, B contains C, and C contains D. finally, almost every source file contains all header files of the project team, resulting in that most compilation time is spent on parsing header files.
A product has an "excellent practice" for merging. C files into a larger. C file through tools, so as to greatly improve the compilation efficiency.
The fundamental reason is that the number of header file parsing is reduced by merging. C files. However, such "good practice" is a violation of the reasonable division of. C files.
Most products need to compile the whole project to modify one code. For practices such as TDD, the compilation time at the module level is required to be controlled at the second level, which is difficult to achieve even if distributed compilation is used. Finally, it is still necessary to reasonably divide the header files and the inclusion relationship between header files, so as to fundamentally reduce the compilation time.
The chapter 1.2 header file dependency in Google C + + + style guide also gives a similar explanation: if the header file AA. H is included, a new dependency is introduced: once AA. H is modified, any code directly or indirectly containing AA. H will be recompiled. If AA. H contains other header files, such as BB. H, any change to BB. H will cause all code containing AA. H to be recompiled.
In the agile development mode, the code will be built frequently, and the long compilation time will greatly hinder the frequent construction. Therefore, we tend to reduce the inclusion of header files, especially in header files, to control the compilation time after code changes.
Reasonable header file division reflects the idea of system design, but from the perspective of programming specification, there are still some general methods to reasonably plan header files. Some methods introduced in this chapter will be helpful for rational planning of header files.
Principle 1: the declaration of the interface in the header file is not suitable for the implementation.
Description: header file is the external interface of module or unit. External declarations should be placed in the header file, such as externally provided function declarations, macro definitions, type definitions, etc.
The declaration of internally used functions (equivalent to private methods of classes) should not be placed in the header file.
Macros, enumerations and structure definitions used internally should not be put into header files.
The variable definition should not be placed in the header file, but in the. C file.
The declaration of variables should not be placed in the header file, that is, try not to use global variables as interfaces. Variables are the internal implementation details of modules or units. They should not be directly exposed to the outside by declaration in the header file, but should be exposed to the outside by function interface.
Extended reading material: C language interface and Implementation
Principle 2: the header file should have a single responsibility.
Note: the header file is too complex and the dependency is too complex, which is the main reason for the long compilation time. In many existing codes, the header files are too large, too many responsibilities, and the problem of circular dependency may lead to the inclusion of more than a dozen header files in order to use a macro in. C.
A header file not only defines the basic data type word, but also contains uncommon header files such as stdio. H and syslib. H.
If there are 10000 source files in the project, and 100 of them use printf of stdio. H, the responsibilities of the above header files are too large, and word must be included in each file, resulting in 9900 unnecessary expansions of stdio. H / syslib. H, which greatly increases the compilation time of the project.
Principle 3: header files should be included in a stable direction.
Note: the inclusion relationship of header file is a dependency. Generally speaking, unstable modules should be allowed to rely on stable modules, so that when unstable modules change, stable modules will not be affected (compiled).
For our products, the direction of dependence should be: the products depend on the platform, and the platform depends on the standard library. The code of a product line platform already contains the product header file, which makes the platform unable to compile, release and test independently. This is a very bad counterexample.
In addition to the unstable module depending on the stable module, the better way is that the two modules depend on the interface together, so that the internal implementation change of any module does not need to recompile the other module. Here, we assume that the interface itself is the most stable.
Extended reading materials: the editor recommends that developers use the "dependency inversion" principle, that is, the user formulates the interface and the service provider implements the interface. For a more specific description, see the chapter "agile design" in part II of agile software development: principles, patterns and practices (translated by Robert C. Martin, translated by Deng Hui, Tsinghua University Press, September 2003).
Rule 1: each. C file should have an. H file with the same name, which is used to declare the interface that needs to be exposed to the public.
Note: if a. C file does not need to publish any interface, it should not exist unless it is the entry of the program, such as the file where the main function is located.
In some existing products, it is customary for a. C file to correspond to two header files. One is used to store the publicly disclosed interface and the other is used to store the definitions and declarations required internally to control the number of lines of code in the. C file. The editor does not advocate this style.
The root of this style is that the source file is too large. You should first consider splitting the. C file to make it not too large. In addition, once private definitions and declarations are put into independent header files, it is impossible to technically avoid being included by others, and it is difficult to ensure that these definitions are really private in the end.
The reverse of this rule is not necessarily true. Some particularly simple header files, such as command ID definition header files, do not need to have a corresponding. C [A1].
Example: for the following scenarios, for example, there is a function call relationship in a. C:
void foo（） { bar（）; } void bar（） { Do something; }
Bar must be declared before foo, otherwise it will cause compilation errors.
The function declaration of this class should be declared in the header of. C and declared as static, as follows:
static void bar（）; void foo（） { bar（）; } void bar（） { Do something; }
Rule 2: circular dependency of header files is prohibited.
Note: cyclic dependency of header file means that A.H contains B.H, B.H contains C.H, and C.H contains A.H. any modification of header file will lead to the recompilation of all codes containing A.H / B.H / C.H.
If it is a one-way dependency, for example, A.H contains B.H, B.H contains C.H, and C.H does not contain any header files, modifying A.H will not cause the source code containing B.H / C.H to be recompiled.
Rule 3:. C /. H files are prohibited from containing unused header files.
Note: header files in many systems contain complex relationships. Developers may not study them one by one to save trouble. They directly include all the header files they think of. Even some products simply release a God. H, which contains all the header files, and then release them to various project teams for use. This is just a temporary and easy way, It leads to the further deterioration of the compilation time of the whole system, and causes great trouble for the maintenance of later people.
Rule 4: header files should be self-contained.
Note: in short, self-contained means that any header file can be compiled independently. If a header file contains one header file and another header file to work, it will increase communication barriers and add unnecessary burden to the users of this header file [A2].
Example: if A.H is not self-contained and needs to include B.H to compile, it will bring harm: each. C file using A.H header file must include additional header file B.H in order to compile the contents of the imported A.H. The additional header file B.H must be included before A.H, which has a dependency on the inclusion order.
Note: this rule needs to be used together with the rule of ". C /. H files are prohibited from including unused header files". Unnecessary header files cannot be included in A.H in order to make A.H self-contained. a. H should just be self-contained. You can't include any header files other than self-contained in A.H.
Rule 5: always write an internal #include protector (#define protection).
Note: including a header file multiple times can be avoided through careful design. If you can't do this, you need to adopt a mechanism to prevent the contents of the header file from being included more than once.
The usual method is to configure a macro for each file, define the macro when the header file is included for the first time, and use it to exclude the file content when the header file is included again.
All header files should be named filename using #define to prevent multiple inclusion of header files_ H. To ensure uniqueness, a better name is ProjectName_ PATH_ FILENAME_ H。
Note: if you do not add "" at the beginning of the macro, you will use filename_ H substitution_ FILENAME_ H. This is because identifiers starting with "" and "" are generally reserved for the system or used by the standard library. In some static inspection tools, if globally visible identifiers start with "", an alarm will be given.
When defining the inclusion of protectors, the following rules should be observed:
1) The protector uses a unique name;
2) Do not place code or comments before or after the protected part.
Example: it is assumed that the timer. H of the timer module of the Vos project, whose directory is Vos / include / timer / timer. H, should be protected as follows:
#ifndef VOS_ INCLUDE_ TIMER_ TIMER_ H #define VOS_ INCLUDE_ TIMER_ TIMER_ H 。.. # endif
You can also use the following simple ways to protect:
#ifndef TIMER_ H #define TIMER_ H 。. # endif
Exception: the copyright notice part of the header file and the overall comment part of the header file (such as describing the development background and precautions of the header file) can be placed in the protector (#ifndef XX)_ H) Front.
Rule 6: it is forbidden to define variables in header files.
Note: defining variables in the header file will lead to repeated definition of variables because the header file is included in other. C files.
Rule 7: other interfaces provided by. C can only be used by including header files. It is prohibited to use external function interfaces and variables [A3] through extern in. C.
Note: if A.C uses the foo() function defined by B.C, external int foo (int input) should be declared in B.H; And use foo through #include in a.c.
It is forbidden to write extern int foo (int input) directly in a.c; To use foo, which is easy to write in F
Our other product:
