Code specifications are very important requirements for a project, a team, and even a company.
There is the "Java Development Manual" published by Ali in China, but Java is only one of many popular languages. Many languages are quite different from Java due to grammatical rules, compilation process, and memory management. This article shows the specifications that need to be paid attention to in the C++ coding process by translating the Google C++ Style Guide .
background
C++ is one of the main development languages used by many Google open source projects. Every C++ programmer knows that the language has many powerful features, but this feature brings complexity that makes the code more prone to errors and difficult to read and maintain.
The purpose of this guide is to manage this complexity by describing in detail the considerations for writing C++ code. These rules exist to make the code base easy to manage, while still allowing coders to effectively use C++ language features.
Style (also known as readability) is a convention we use to control C++ code. The term "style" is a bit of a misnomer, because these conventions cover not only the source file format, but also more content.
Most open source projects developed by Google meet the requirements of this guide.
Please note that this guide is not a C++ tutorial: we assume that the reader is familiar with the language.
The purpose of this article
Why this article
We believe that this guide should achieve some core goals, and these are the root causes behind all the rules. By highlighting these ideas, we hope to be able to discuss and make our wider community more aware of why the rules were made and why specific decisions were made. If you understand the goals that each rule serves, you should let everyone (and in some cases give up) a clearer understanding of each rule, and the arguments or alternatives needed to change the rule in the guide.
- Style rules should play a role
The benefits of style rules must be large enough to justify requiring all of our engineers to remember it. The benefits are measured relative to the code base we would get without this rule, so if people are unwilling to do this anyway, the rules for very harmful practices may still generate small gains. This principle mainly explains the rules we don’t have, not the rules we follow: for example, goto violates many of the following principles, but has rarely disappeared, so the style guide is no longer discussed. - Optimizing for readers, not writers
Our code base (and most of the individual components submitted to it) is expected to last a long time. As a result, it will take more time to read most of our code than writing code. We explicitly choose to optimize the experience of ordinary software engineers in reading, maintaining and debugging the code in our code base, rather than making it easy when writing the code. "Leave a trace for the reader" is a particularly common sub-point of the principle: when something surprising or unusual occurs in a piece of code (for example, the transfer of pointer ownership), at this time, the reader is left with text The use of hints is very valuable (std::unique_ptr clearly demonstrates the ownership transfer at the calling site). - Consistent with existing code
Using a style consistently in our code base allows us to focus on other (more important) issues. Consistency can also be automated: tools that format code or adjust code #include will only work if the code is consistent with the expectations of the tool. In many cases, the rule attributed to "be consistent" can be boiled down to "just choose one and stop worrying." The potential value of allowing flexibility on these issues is offset by the cost of arguing about them. - Alignment with the wider C++ community when appropriate. It
is valuable to align with the way other organizations use C++, and for the same reasons as in our codebase. If a feature in the C++ standard solves the problem, or an idiom is widely known and accepted, then this is the reason to use it. However, sometimes the standard functions and idioms are flawed, or the requirements of our code base are not considered in the design. In this case (described below), standard functions should be restricted or prohibited. In some cases, due to the perceived advantage or value that is not enough to transition the code base to a standard interface, we prefer to use a native library or a third-party library instead of the library defined in the C++ standard. - Avoid surprising or dangerous constructions
C++ has more surprising or dangerous functions than one can think of at a glance. Some style guides are restricted in place to prevent falling into these traps. For such restrictions, the threshold for abandoning the style guide is very high, because abandoning such rules usually directly damages the correctness of the program. - Avoid structures that ordinary C++ programmers will find tricky or difficult to maintain.
Because C++ introduces the complexity of the code, C++ has features that may usually be inappropriate. In widely used code, it may be more acceptable to use more skillful language constructs, because any benefits brought by more complex implementations will be multiplied by use, and there is no need to pay for understanding when using complex language parts. The cost of complexity. Code library. If in doubt, you can seek exemptions from such rules by asking your project leader. This is particularly important for our code base, because code ownership and team member relationships will change over time: even if everyone who currently uses a piece of code can understand it, there is still no guarantee that this understanding will last for several years. - Pay attention to our scale.
With 100+ million lines of code base and a code base of thousands of engineers, for an engineer, some mistakes and simplifications may cost many people a high price. For example, it is especially important to avoid polluting the global namespace: name conflicts in a code base spanning hundreds of millions of lines are difficult to deal with, and if everyone puts them in the global namespace, it is difficult to avoid. - Consider optimization when necessary.
Performance optimization may sometimes be necessary and appropriate, even if they conflict with other principles of this document.
In this way, we specifically refer to the established practices of the entire Google C++ community, not just your personal or team personal preferences. Be skeptical and unwilling to use clever or unusual constructs: no prohibition is equivalent to permission. Use your judgment. If you are not sure, please do not hesitate to ask your project leader to get other opinions.
This article applies to C++ 17 and does not fully adapt to C++ 2X
head File
Generally, every .cc file should have an associated .h file. There are some common exceptions, such as unit tests and .cc small files that only contain the main() function.
Correct use of header files can have a huge impact on the readability, size and performance of the code.
The following rules will guide you to solve various pitfalls of using header files.
Separate header file
The header file should be capable of independent self-compilation and end with .h. Non-header files that you intend to include should end with .inc and should be used with caution.
All header files should be independent. Users and refactoring tools do not have to comply with special conditions to include the title. Specifically, the header should have header protection and include all other headers it needs.
It is best to put the definitions of templates and inline functions in the same file as their declarations. The definitions of these structures must be included in every .cc file that uses them, otherwise the program may not be able to link in some structure configurations. If the declaration and definition are in different documents, the former should transitively include the latter. Do not move these definitions into a separately included header file (-inl.h); this practice was common in the past, but it is no longer allowed.
As an exception, it is allowed to define a template that is explicitly instantiated for all related template parameter sets in a unique .cc instantiation template file, or the private implementation details of the class.
In rare cases, files designed to be included are not self-contained. They are usually included in unusual locations, such as the middle of another file. They may not use title protection, or they may not include its prerequisites. Use the .inc extension to name such files. Use it sparingly, and use separate headers whenever possible.
#define protection
All header files should have #define protection measures to prevent multiple inclusions. The format of the symbol name should be.
<PROJECT>_<PATH>_<FILE>_H_
To ensure uniqueness, they should be based on the full path in the project source tree. For example, the file foo in the foo/src/bar/baz.h project should have the following protections:
#ifndef FOO_BAR_BAZ_H_
＃定义FOO_BAR_BAZ_H_
...
#endif // FOO_BAR_BAZ_H_