From 3917d8ab03b5677dda1be7a0c36725057cda5bd2 Mon Sep 17 00:00:00 2001
From: ARUL DEVARAJAN <arulkumaran.devarajan@huawei.com>
Date: Fri, 12 Mar 2021 07:46:12 +0000
Subject: [PATCH] Style Guide: Removed Style Guide
* Signed-off By: Arul Kumaran <arulkumaran.devarajan@huawei.com>
---
README.rst | 2 -
readme/C++ Coding Style Guide.rst | 3616 ----------------------
readme/Contributing to the Code.rst | 23 -
readme/JavaScript Coding Style Guide.rst | 968 ------
readme/README.rst | 3 -
5 files changed, 4612 deletions(-)
delete mode 100644 readme/C++ Coding Style Guide.rst
delete mode 100644 readme/Contributing to the Code.rst
delete mode 100644 readme/JavaScript Coding Style Guide.rst
diff --git a/README.rst b/README.rst
index 21ad94d..44331fb 100644
--- a/README.rst
+++ b/README.rst
@@ -35,8 +35,6 @@ We welcome you to join the project |main_project_name| and support us in buildin
* All our documents are written in reStructuredText for easy of writing and processing to different format. You can use ReadTheDoc to publish our documents into anyformat you want, or locally generate the required format output using the Sphinx document generator. For more details, refer `Documentation using Sphinx <https://openharmony.readthedocs.io/en/latest/readme/reStructuredText%20Basics.html>`_
-* In order to maintain consistency across code base, refer to the `coding style guide <https://openharmony.readthedocs.io/en/latest/readme/Contributing%20to%20the%20Code.html>`_ before you stat contributing to the code base of |main_project_name|.
-
Where to Turn for Help
**********************
You can subscribe to the mailing list to get constant updates on new features, release road maps, and community activities. For Subscribing to the mailing list or any other support, see `Communication in Community <https://openharmony.readthedocs.io/en/latest/readme/Communication%20in%20Community.html>`_.
diff --git a/readme/C++ Coding Style Guide.rst b/readme/C++ Coding Style Guide.rst
deleted file mode 100644
index b33639f..0000000
--- a/readme/C++ Coding Style Guide.rst
+++ /dev/null
@@ -1,3616 +0,0 @@
-.. _C++coding-style:
-
-.. include:: ../definitions.rst
-
-C++ Coding Style Guide
-######################
-
-Purpose
-*******
-Rules are not perfect. Disabling useful features in specific situations may affect code implementation. However, the rules are formulated "to help most programmers to get more benefits". If a rule is found unhelpful or difficult to follow in team coding, please send your feedback to us so we can improve the rule accordingly. Before referring to this guide, you are expected to have the following basic capabilities for C++. It is not for a beginner that wants to learn about C++.
-
-#. Have a general knowledge of ISO standards for C++.
-#. Be familiar with the basic features of C++, including those of C++ 03/11/14/17.
-#. Have a general knowledge of the C++ Standard Library.
-
-General Principles
-******************
-Code must meet the requirements for readability, maintainability, security, reliability, testability, efficiency, and portability while ensuring functionality correctness.
-
-Conventions
-***********
-
-**Rule**: A regulating principle that must be followed during
-programming.
-
-**Recommendation**: A guideline that must be considered during
-programming.
-
-This document is applicable to standard C++ versions (C++ 03/11/14/17)
-unless otherwise specified in the rule.
-
-Exceptions
-**********
-
-It is necessary to understand the reason for each rule or recommendation
-and to try and comply with them. However, some rules and recommendations
-have exceptions.
-
-The only acceptable exceptions are those that do not violate the general
-principles and provide appropriate reasons for the exception. Try to
-avoid exceptions because they affect the code consistency. Exceptions to
-‘Rules’ should be very rare.
-
-The style consistency principle is preferred in the following case:
-When you modify external open source or third-party code, the existing code specifications prevail.
-
-Naming
-******
-
-General Naming Rules
-====================
-
-**CamelCase** CamelCase is the practice of writing compound words or
-phrases so that each word or abbreviation in the phrase begins with a
-capital letter, with no intervening spaces or punctuation. There are two
-conventions: UpperCamelCase and lowerCamelCase.
-
-+----------------------------------+--------------------------+
-| Type | Naming Style |
-+==================================+==========================+
-| Class Type, Struct Type, | UpperCamelCase |
-| Enumeration Type, and Union Type | |
-| Definitions, Scope Name | |
-+----------------------------------+--------------------------+
-| Functions (Including Global | UpperCamelCase |
-| Functions, Scope Functions, and | |
-| Member Functions) | |
-+----------------------------------+--------------------------+
-| Global Variables (Including | lowerCamelCase |
-| Variables of the Global and | |
-| Namespace Scopes, Namespace | |
-| Variables, and Class Static | |
-| Variables), Local Variables, | |
-| Function Parameters, and Class, | |
-| Struct, and Union Member | |
-| Variables | |
-+----------------------------------+--------------------------+
-| Macro, Constant, Enumerated | All caps, separated with |
-| Value, goto Tag | underscores (``_``) |
-+----------------------------------+--------------------------+
-
-Note: **Constant** indicates the variables of the basic, enumeration, or
-character string type modified by const or constexpr in the global
-scope, the namespace scope, and the scope of a static member of a class.
-**Variable** indicates the variables excluding those defined in
-**Constant**. These variables use the lowerCamelCase style.
-
-File Names
-==========
-
-Recommendation 2.2.1 Use .cpp as the C++ file name extension and .h as the header file name extension.
-------------------------------------------------------------------------------------------------------
-
-It is recommended that you use .h as the name extension of a header file
-so that the header file can be directly compatible with C and C++. It is
-recommended that you use .cpp as the name extension of an implementation
-file. In this way, you can directly distinguish C++ code from C code.
-
-At present, there are some other file name extensions used by
-programmers:
-
-* Header files: .hh, .hpp, .hxx
-* Implementation files: .cc, .cxx, .C
-
-If your project team uses a specific file name extension, you can
-continue to use it and keep the style consistent. This document uses .h
-and .cpp extensions.
-
-Recommendation 2.2.2 Keep C++ file names the same as the class name.
---------------------------------------------------------------------
-
-The names of the C++ header file and the C++ implementation file must be
-the same as the class name. Use the CamelCase or Kernel style and keep
-the style consistent.
-
-For example, if there is a class named DatabaseConnection, the
-corresponding file names are as follows: - database_connection.h -
-database_connection.cpp
-
-The naming rules of struct, namespace, and enumeration definition files
-are similar to the rules above.
-
-Function Names
---------------
-
-Functions are named in UpperCamelCase. Generally, the verb or
-verb-object structure is used.
-
-.. code:: cpp
-
- class List {
- public:
- void AddElement(const Element& element);
- Element GetElement(const unsigned int index) const;
- bool IsEmpty() const;
- };
-
- namespace Utils {
- void DeleteUser();
- }
-
-Type Names
-----------
-
-Types are named in the UpperCamelCase style. All types, such as classes,
-structs, unions, typedefs, and enumerations, use the same conventions.
-For example:
-
-.. code:: cpp
-
- // classes, structs and unions
- class UrlTable { ...
- class UrlTableTester { ...
- struct UrlTableProperties { ...
- union Packet { ...
-
- // typedefs
- typedef std::map<std::string, UrlTableProperties*> PropertiesMap;
-
- // enums
- enum UrlTableErrors { ...
-
-For namespace naming, UpperCamelCase is recommended.
-
-.. code:: cpp
-
- // namespace
- namespace OsUtils {
-
- namespace FileUtils {
-
- }
-
- }
-
-Recommendation 2.4.1 Do not abuse typedef or #define to alias basic types.
---------------------------------------------------------------------------
-
-Unless otherwise specified, do not use typedef or #define to redefine a
-basic value type. The basic types found in the ``<cstdint>`` header file
-are preferable.
-
-+----------+-----------+--------------------------------------------+
-| Signed | Unsigned | Description |
-| Type | Type | |
-+==========+===========+============================================+
-| int8_t | uint8_t | The signed or unsigned 8-bit integer type. |
-+----------+-----------+--------------------------------------------+
-| int16_t | uint16_t | The signed or unsigned 16-bit integer |
-| | | type. |
-+----------+-----------+--------------------------------------------+
-| int32_t | uint32_t | The signed or unsigned 32-bit integer |
-| | | type. |
-+----------+-----------+--------------------------------------------+
-| int64_t | uint64_t | The signed or unsigned 64-bit integer |
-| | | type. |
-+----------+-----------+--------------------------------------------+
-| intptr_t | uintptr_t | The signed or unsigned integer type large |
-| | | enough to hold a pointer. |
-+----------+-----------+--------------------------------------------+
-
-Variable Names
---------------
-
-General variables are named in lowerCamelCase, including global
-variables, function parameters, local variables, and member variables.
-
-.. code:: cpp
-
- std::string tableName; // Good: Recommended style.
- std::string tablename; // Bad: Forbidden style.
- std::string path; // Good: When there is only one word, lowerCamelCase (all lowercase) is used.
-
-Rule 2.5.1 Add the prefix ‘g\_’ to global variables. Do not add a prefix to a static variable.
-----------------------------------------------------------------------------------------------
-
-Global variables should be used as little as possible, and special
-attention should be paid to the use of global variables. This prefix
-highlights global variables so that developers can be more careful when
-handling them. - Global static variables and global variables are named
-in the same way. - Static variables and common local variables in
-functions are named in the same way. - Static member variables and
-common member variables of classes are named in the same way.
-
-.. code:: cpp
-
- int g_activeConnectCount;
-
- void Func()
- {
- static int packetCount = 0;
- ...
- }
-
-Rule 2.5.2 Name member variables in classes based on the three styles of the lowerCamelCase and maintain a uniform coding style for a product or project.
----------------------------------------------------------------------------------------------------------------------------------------------------------
-
-.. code:: cpp
-
- class Foo {
- private:
- std::string fileName_; // Add the _ postfix, similar to the K&R naming style.
- };
-
-Use the lowerCamelCase style and do not add prefixes or suffixes to name
-a member variable of the struct or union type. Keep the naming style
-consistent with that for a local variable.
-
-Macro, Constant, and Enumeration Names
---------------------------------------
-
-For macros and enumerated values, use all caps separated with
-underscores (``_``). In the global scope, constants of named and unnamed
-namespaces and static member constants should be capitalized and
-separated with underscores (``_``). Local constants and ordinary const
-member variables use the lowerCamelCase naming style.
-
-.. code:: cpp
-
- #define MAX(a, b) (((a) < (b))? (b): (a)) // Though examples of Macro names are made, you are not advised to use macros to implement this function.
-
- enum BaseColor { // Note: Enumerated types are named in the UpperCamelCase style, while their values are all capitalized and separated with underscores (_).
- RED,
- DARK_RED,
- GREEN,
- LIGHT_GREEN
- };
-
- int Func(...)
- {
- const unsigned int bufferSize = 100; // Local variable
- char *p = new char[bufferSize];
- ...
- }
-
- namespace Utils {
- const unsigned int DEFAULT_FILE_SIZE_KB = 200; // Global variable
- }
-
-Formatting
-**********
-
-Line Length
-===========
-
-Recommendation 3.1.1 Each line of code should contain a maximum of 120 characters.
-----------------------------------------------------------------------------------
-
-\*\* Note: \**It is recommended that the number of characters in each
-line not exceed 120. It is recommended that the number of characters in
-each line not exceed 120. If the line of code exceeds the permitted
-length, wrap the line appropriately.
-
-Exception: - If a one-line comment contains a command or URL of more
-than 120 characters, you can keep the line for ease in using copy,
-paste, and search using the grep command. - The length of an
-``#include`` statement can contain a long path exceeding 120 characters,
-but this should be avoided if possible. - The error information in
-preprocessor directives can exceed the permitted length. Put the error
-information of preprocessor directives in one line to facilitate reading
-and understanding even if the line contains more than 120 characters.
-
-.. code:: cpp
-
- #ifndef XXX_YYY_ZZZ
- #error Header aaaa/bbbb/cccc/abc.h must only be included after xxxx/yyyy/zzzz/xyz.h, because xxxxxxxxxxxxxxxxxxxxxxxxxxxxx
- #endif
-
-Indentation
-===========
-
-Rule 3.2.1 Use spaces to indent and indent 4 spaces at a time.
---------------------------------------------------------------
-
-Only spaces can be used for indentation. Four spaces are indented each
-time. Do not use the Tab character to indent. Currently, almost all IDEs
-support automatic expansion of a Tab to 4 spaces upon pressing the tab
-key. Please configure your IDE to do so.
-
-Braces
-======
-
-Rule 3.3.1 Use the K&R indentation writing style.
--------------------------------------------------
-
-**K&R style** When a line break is required, the left brace of a
-function (excluding the lambda statement) starts a new line. One space
-should be placed between the statement and the brace. The right brace
-starts a new line and nothing else is placed on the line, unless it is
-followed by the remaining part of the same statement, for example,
-“while†in the do statement, “else†or “else if†in the if statement, a
-comma, and a semicolon.
-
-For example:
-
-.. code:: cpp
-
- struct MyType { // Follow the statement to the end, and indent one space.
- ...
- };
-
- int Foo(int a)
- { // The left brace of the function starts a new line, nothing else is placed on the line.
- if (...) {
- ...
- } else {
- ...
- }
- }
-
-The reasons for recommending this style are as follows:
-
-- Code is more compact.
-- Placing the brace at the end of the statement makes the code more
- continuous in reading rhythm than starting a new line.
-- This style complies with mainstream norms and habits of programming
- languages.
-- Most modern IDEs have an automatic code indentation, alignment and
- display. Placing the brace at the end of a line does not impact
- understanding.
-
-If no function body is inside the braces, the braces can be put on the
-same line.
-
-.. code:: cpp
-
- class MyClass {
- public:
- MyClass() : value_(0) {}
-
- private:
- int value_;
- };
-
-Function Declarations and Definitions
-=====================================
-
-Rule 3.4.1 The return type and the function name of a function declaration or definition must be on the same line. When the length of the function parameter list exceeds the permitted length, a line break is required and parameters must be aligned appropriately.
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-
-When a function is declared or defined, the return value type of the
-function should be on the same line as the function name. If the line
-length permits, the function parameters should be placed on the same
-line. Otherwise, the function parameters should be wrapped and properly
-aligned. The left parenthesis of a parameter list should always be on
-the same line as the function name. The right parenthesis always follows
-the last parameter.
-
-The following is an example of line breaks:
-
-.. code:: cpp
-
- ReturnType FunctionName(ArgType paramName1, ArgType paramName2) // Good: All are in the same line.
- {
- ...
- }
-
- ReturnType VeryVeryVeryLongFunctionName(ArgType paramName1, // Each added parameter starts on a new line because the line length limit is exceeded.
- ArgType paramName2, // Good: aligned with the previous parameter.
- ArgType paramName3)
- {
- ...
- }
-
- ReturnType LongFunctionName(ArgType paramName1, ArgType paramName2, // Parameters are wrapped because the line length limit is exceeded.
- ArgType paramName3, ArgType paramName4, ArgType paramName5) // Good: After the line break, 4 spaces are used for indentation.
- {
- ...
- }
-
- ReturnType ReallyReallyReallyReallyLongFunctionName( // The line length cannot accommodate even the first parameter, and a line break is required.
- ArgType paramName1, ArgType paramName2, ArgType paramName3) // Good: After the line break, 4 spaces are used for indentation.
- {
- ...
- }
-
-Function Calls
-==============
-
-Rule 3.5.1 A function call parameter list should be placed on one line. When the parameter list exceeds the line length and requires a line break, the parameters should be properly aligned.
----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-
-A function call parameter list should be placed on one line. When the
-parameter list exceeds the line length and requires a line break, the
-parameters should be properly aligned. The left parenthesis always
-follows the function name, and the right parenthesis always follows the
-last parameter.
-
-The following are examples of proper line breaks:
-
-.. code:: cpp
-
- ReturnType result = FunctionName(paramName1, paramName2); // Good: All function parameters are on one line.
-
- ReturnType result = FunctionName(paramName1,
- paramName2, // Good: aligned with the previous parameter
- paramName3);
-
- ReturnType result = FunctionName(paramName1, paramName2,
- paramName3, paramName4, paramName5); // Good: Parameters are wrapped. After the line break, 4 spaces are used for indentation.
-
- ReturnType result = VeryVeryVeryLongFunctionName( // The line length cannot accommodate even the first parameter, and a line break is required.
- paramName1, paramName2, paramName3); // After the line break, 4 spaces are used for indentation.
-
-If some of the parameters called by a function are associated with each
-other, you can group them for better understanding.
-
-.. code:: cpp
-
- // Good: The parameters in each line represent a group of data structures with strong correlation. They are placed on a line for ease of understanding.
- int result = DealWithStructureLikeParams(left.x, left.y, // A group of related parameters.
- right.x, right.y); // Another group of related parameters.
-
-if Statements
-=============
-
-Rule 3.6.1 Use braces to include an if statement.
--------------------------------------------------
-
-We require that all if statements use braces, even if there is only one
-statement.
-
-Reasons: - The logic is intuitive and easy to read. - It is less prone
-to mistakes when new code is added to the existing if statement. - If
-function-like macros are used in a conditional statement, it is less
-prone to mistakes (in case the braces are missing when macros are
-defined).
-
-.. code:: cpp
-
- if (objectIsNotExist) { // Good: Braces are added to a single-line conditional statement.
- return CreateNewObject();
- }
-
-Rule 3.6.2 Place if, else, and else if keywords on separate lines.
-------------------------------------------------------------------
-
-If there are multiple branches in a conditional statement, they should
-be placed on separate lines.
-
-Good example:
-
-.. code:: cpp
-
- if (someConditions) {
- DoSomething();
- ...
- } else { // Good: Put the if and else keywords on separate lines.
- ...
- }
-
-Bad example:
-
-.. code:: cpp
-
- if (someConditions) { ... } else { ... } // Bad: The if and else keywords are put on the same line.
-
-Loop Statements
-===============
-
-Rule 3.7.1 Use braces after loop statements.
---------------------------------------------
-
-Similar to if statements, we require that the for and while loop
-statements contain braces, even if the loop body is empty or there is
-only one loop statement.
-
-.. code:: cpp
-
- for (int i = 0; i < someRange; i++) { // Good: Braces are used.
- DoSomething();
- }
-
-.. code:: cpp
-
- while (condition) {} // Good: The while loop body is empty. Braces should be used.
-
-.. code:: cpp
-
- while (condition) {
- continue; // Good: The continue keyword highlights the end of the empty loop. Braces should be used.
- }
-
-Bad example:
-
-.. code:: cpp
-
- for (int i = 0; i < someRange; i++)
- DoSomething(); // Bad: Braces are mandatory.
-
-.. code:: cpp
-
- while (someCondition) ; // Bad: Using a semicolon here will make people misunderstand that it is a part of the while statement and not the end to it.
-
-Switch Statements
-=================
-
-Rule 3.8.1 Indent case and default in a switch statement with four spaces.
---------------------------------------------------------------------------
-
-The indentation style of the switch statement is as follows:
-
-.. code:: cpp
-
- switch (var) {
- case 0: // Good: Indented
- DoSomething1(); // Good: Indented
- break;
- case 1: { // Good: Braces are added.
- DoSomething2();
- break;
- }
- default:
- break;
- }
-
-.. code:: cpp
-
- switch (var) {
- case 0: // Bad: case is not indented.
- DoSomething();
- break;
- default: // Bad: default is not indented.
- break;
- }
-
-Expressions
-===========
-
-Recommendation 3.9.1 Keep a consistent line break style for expressions and ensure that operators are placed at the end of a line.
-----------------------------------------------------------------------------------------------------------------------------------
-
-A long expression that does not meet the line length requirement must be
-wrapped appropriately. Generally, the expression is wrapped at an
-operator of a lower priority or a connector, and the operator or
-connector is placed at the end of the line. Placing these at the end of
-a line indicates that the operation is to be continued on the next line.
-For example:
-
-// Assume that the first line exceeds the length limit.
-
-.. code:: cpp
-
- if (currentValue > threshold && // Good: After the line break, the logical-AND operators are placed at the end of the line.
- someConditionsion) {
- DoSomething();
- ...
- }
-
- int result = reallyReallyLongVariableName1 + // Good
- reallyReallyLongVariableName2;
-
-After an expression is wrapped, ensure that the lines are aligned
-appropriately or indented with 4 spaces. See the following example.
-
-.. code:: cpp
-
- int sum = longVaribleName1 + longVaribleName2 + longVaribleName3 +
- longVaribleName4 + longVaribleName5 + longVaribleName6; // Good: indented with 4 spaces
-
- int sum = longVaribleName1 + longVaribleName2 + longVaribleName3 +
- longVaribleName4 + longVaribleName5 + longVaribleName6; // Good: The lines are aligned.
-
-Variable Assignment
-===================
-
-Rule 3.10.1 Multiple variable definitions and assignment statements cannot be written on one line.
---------------------------------------------------------------------------------------------------
-
-Each line should have only one variable initialization statement. It is
-easier to read and understand.
-
-.. code:: cpp
-
- int maxCount = 10;
- bool isCompleted = false;
-
-Bad example:
-
-.. code:: cpp
-
- int maxCount = 10; bool isCompleted = false; // Bad: Multiple variable initialization statements must be separated on different lines. Each variable initialization statement occupies one line.
- int x, y = 0; // Bad: Multiple variable definitions must be separated on different lines. Each definition occupies one line.
-
- int pointX;
- int pointY;
- ...
- pointX = 1; pointY = 2; // Bad: Multiple variable assignment statements must be separated on different lines.
-
-Exception: Multiple variables can be declared and initialized in the for
-loop header, if initialization statement (C++17), and structured binding
-statement (C++17). Multiple variable declarations in these statements
-have strong associations. Forcible division into multiple lines may
-cause problems such as scope inconsistency and separation of declaration
-from initialization.
-
-Initialization
-==============
-
-Initialization is applicable to structs, unions, and arrays.
-
-Rule 3.11.1 When an initialization list is wrapped, ensure that the line after the break is indented and aligned properly.
---------------------------------------------------------------------------------------------------------------------------
-
-If a structure or array initialization list is wrapped, the line after
-the break is indented with four spaces. Choose the wrap location and
-alignment style for best comprehension.
-
-.. code:: cpp
-
- const int rank[] = {
- 16, 16, 16, 16, 32, 32, 32, 32,
- 64, 64, 64, 64, 32, 32, 32, 32
- };
-
-Pointers and References
-=======================
-
-Recommendation 3.12.1 The pointer type ``*`` follows a variable name or type. There can be only one space to the side of it.
-----------------------------------------------------------------------------------------------------------------------------
-
-Pointer naming: There can be only one space next to ``*``.
-
-.. code:: cpp
-
- int* p = NULL; // Good
- int *p = NULL; // Good
-
- int*p = NULL; // Bad
- int * p = NULL; // Bad
-
-Exception: When a variable is modified by const or restrict, ``*``
-cannot follow the variable or type.
-
-.. code:: cpp
-
- const char * const VERSION = "V100";
-
-Recommendation 3.12.2 The reference type ``&`` follows a variable name or type. There can be only one space to the side of it.
-------------------------------------------------------------------------------------------------------------------------------
-
-Reference naming: There can be only one space around ``&``.
-
-.. code:: cpp
-
- int i = 8;
-
- int& p = i; // Good
- int &p = i; // Good
- int*& rp = pi; // Good: The reference type `*&` follows the type.
- int *&rp = pi; // Good: The reference type `*&` follows the variable name.
- int* &rp = pi; // Good: The pointer type `*` follows the type and the eference type `&` follows the variable name.
-
- int & p = i; // Bad
- int&p = i; // Bad
-
-Preprocessor Directives
-=======================
-
-Rule 3.13.1 The number sign (#) that starts a preprocessor directive must be at the beginning of the line and can be indented in nested preprocessor directives.
-----------------------------------------------------------------------------------------------------------------------------------------------------------------
-
-The number sign (#) that starts a preprocessor directive must be at the
-beginning of the line even through the preprocessor directive is inside
-a function.
-
-.. code:: cpp
-
- #if defined(__x86_64__) && defined(__GCC_HAVE_SYNC_COMPARE_AND_SWAP_16) // Good: "#" is at the beginning of the line.
- #define ATOMIC_X86_HAS_CMPXCHG16B 1 // Good: "#" is at the beginning of the line.
- #else
- #define ATOMIC_X86_HAS_CMPXCHG16B 0
- #endif
-
-
- int FunctionName()
- {
- if (someThingError) {
- ...
- #ifdef HAS_SYSLOG // Good: Even in the function body, "#" is at the beginning of the line.
- WriteToSysLog();
- #else
- WriteToFileLog();
- #endif
- }
- }
-
-The nested preprocessor directives starting with ``#`` can be indented
-and aligned based on a standardized style.
-
-.. code:: cpp
-
- #if defined(__x86_64__) && defined(__GCC_HAVE_SYNC_COMPARE_AND_SWAP_16)
- #define ATOMIC_X86_HAS_CMPXCHG16B 1 // Good: wrapped for easier comprehension
- #else
- #define ATOMIC_X86_HAS_CMPXCHG16B 0
- #endif
-
-Whitespace
-==========
-
-Rule 3.14.1 Ensure that horizontal spaces are used to highlight keywords and important information, and avoid unnecessary whitespace.
--------------------------------------------------------------------------------------------------------------------------------------
-
-Horizontal spaces are used to highlight keywords and important
-information. Spaces are not allowed at the end of each code line. The
-general rules are as follows:
-
-- Add spaces after keywords such as if, switch, case, do, while, and
- for.
-- Do not add spaces after the left parenthesis or before the right
- parenthesis.
-- For expressions enclosed by braces, either add a space on either side
- or avoid a space on either side.
-- Do not add spaces after any unary operator (& \* + - ~ !).
-- Add a space to the left and right sides of each binary operator (= +
- -< > \* /% \| & ^ <= >= == !=).
-- Add spaces to the left and right sides of a ternary operator (? :).
-- Do not add spaces between a prefix or suffix increment (++) or
- decrement (–) operator and a variable.
-- Do not add spaces before or after a struct member operator (. ->).
-- Do not add spaces before commas. Add spaces after commas.
-- Do not add spaces between a template or type conversion operator (<>)
- and a type.
-- Do not add spaces before or after a domain operator (::).
-- Determine whether to add spaces before and after a colon (:) based on
- the actual situation.
-
-In normal cases:
-
-.. code:: cpp
-
- void Foo(int b) { // Good: A space is added before the left brace.
-
- int i = 0; // Good: During variable initialization, there should be spaces before and after =. Do not leave a space before the semicolon.
-
- int buf[BUF_SIZE] = {0}; // Good: Spaces are not added in braces.
-
-Function definition and call:
-
-.. code:: cpp
-
- int result = Foo(arg1,arg2);
- ^ // Bad: A space should be added after the comma.
-
- int result = Foo( arg1, arg2 );
- ^ ^ // Bad: Spaces should not be added after the left parenthesis or before the right parenthesis.
-
-Pointer and Address Operator
-
-.. code:: cpp
-
- x = *p; // Good: There is no space between the operator * and the pointer p.
- p = &x; // Good: There is no space between the operator & and the variable x.
- x = r.y; // Good: When a member variable is accessed through the operator (.), no space is added.
- x = r->y; // Good: When a member variable is accessed through the operator (->), no space is added.
-
-Other Operators:
-
-.. code:: cpp
-
- x = 0; // Good: There is a space before and after the assignment operator (=).
- x = -5; // Good: There is no space between the minus sign (–) and the number.
- ++x; //Good: Do not add spaces between a prefix or suffix increment (++) or decrement (--) operator and a variable..
- x--;
-
- if (x && !y) // Good: There is a space before and after the Boolean operator. There is no space between the ! operator and the variable.
- v = w * x + y / z; // Good: There is a space before and after the binary operator.
- v = w * (x + z); // Good: There is no space before or after the expression in the parentheses.
-
- int a = (x < y) ? x : y; // Good: Ternary operator. There is a space before and after ? and :
-
-Loops and Conditional Statements:
-
-.. code:: cpp
-
- if (condition) { // Good: There is a space between the if keyword and the left parenthesis, and no space before or after the conditional statement in the parentheses.
- ...
- } else { // Good: There is a space between the else keyword and the left brace.
- ...
- }
-
- while (conditions) {} // Good: There is a space between the while keyword and the left parenthesis. There is no space before or after the conditional statement in the parentheses.
-
- for (int i = 0; i < someRange; ++i) { // Good: There is a space between the for keyword and the left parenthesis, and after the semicolon.
- ...
- }
-
- switch (condition) { // Good: There is a space after the switch keyword.
- case 0: // Good: There is no space between the case condition and the colon.
- ...
- break;
- ...
- default:
- ...
- break;
- }
-
-Templates and Conversions
-
-.. code:: cpp
-
- // Angle brackets (< and >) are not adjacent to space. There is no space before < or between > and (.
- vector<string> x;
- y = static_cast<char*>(x);
-
- // There can be a space between the type and the pointer operator. Keep the spacing style consistent.
- vector<char *> x;
-
-Scope Operators
-
-.. code:: cpp
-
- std::cout; // Good: Namespace access. Do not leave spaces.
-
- int MyClass::GetValue() const {} // Good: Do not leave spaces in the definition of member functions.
-
-Colons
-
-.. code:: cpp
-
- // Scenarios when space is required
-
- // Good: // Add a space before or after the colon in a derived class definition.
- class Sub : public Base {
-
- };
-
- // Add a space before or after the colon in the initialization list of a constructor function.
- MyClass::MyClass(int var) : someVar_(var)
- {
- DoSomething();
- }
-
- // Add a space before or after the colon in a bit-field.
- struct XX {
- char a : 4;
- char b : 5;
- char c : 4;
- };
-
-.. code:: cpp
-
- // Scenarios when space is not required
-
- // Good: // No space is added before or after the colon next to a class access permission (public or private).
- class MyClass {
- public:
- MyClass(int var);
- private:
- int someVar_;
- };
-
- // No space is added before or after the colon in a switch statement.
- switch (value)
- {
- case 1:
- DoSomething();
- break;
- default:
- break;
- }
-
-Note: Currently, all IDEs support automatic deletion of spaces at the
-end of a line. Please configure your IDE correctly.
-
-Recommendation 3.14.1 Use blank lines only when necessary to keep code compact.
--------------------------------------------------------------------------------
-
-There must be as few blank lines as possible so that more code can be
-displayed for easy reading. Recommendations: - Add blank lines according
-to the correlation between lines. - Consecutive blank lines are not
-allowed inside functions, type definitions, macros, and initialization
-expressions. - A maximum of **two** consecutive blank lines can be used.
-- Do not add blank lines on the first and last lines of a code block in
-braces. This recommendation is not applicable to code block in braces of
-a namespace.
-
-.. code:: cpp
-
- int Foo()
- {
- ...
- }
-
-
-
- int bar() {// Bad: More than one blank lines are used between two function definitions.
- {
- ...
- }
-
-
- if (...) {
- // Bad: Do not add blank lines on the first and last lines of a code block.
- ...
- // Bad: Do not add blank lines on the first and last lines of a code block.
- }
-
- int Foo(...)
- {
- // Bad: Do not add blank lines before the first statement in a function body.
- ...
- }
-
-Classes
-=======
-
-Rule 3.15.1 Class access specifier declarations are in the sequence: public, protected, private. Indent these specifiers to the same level as the class keyword.
-----------------------------------------------------------------------------------------------------------------------------------------------------------------
-
-.. code:: cpp
-
- class MyClass : public BaseClass {
- public: // Not indented.
- MyClass(); // Indented with 4 spaces.
- explicit MyClass(int var);
- ~MyClass() {}
-
- void SomeFunction();
- void SomeFunctionThatDoesNothing()
- {
- }
-
- void SetVar(int var) { someVar_ = var; }
- int GetVar() const { return someVar_; }
-
- private:
- bool SomeInternalFunction();
-
- int someVar_;
- int someOtherVar_;
- };
-
-In each part, it is recommended that similar statements be put together
-and in the following order: Type (including typedef, using, nested
-structs and classes), Constant, Factory Function, Constructor,
-Assignment Operator, Destructor, Other Member Function, and Data Member
-
-Rule 3.15.2 The constructor initialization list must be on the same line or wrapped and aligned with four spaces of indentation.
---------------------------------------------------------------------------------------------------------------------------------
-
-.. code:: cpp
-
- // If all variables can be placed on the same line
- MyClass::MyClass(int var) : someVar_(var)
- {
- DoSomething();
- }
-
- // If the variables cannot be placed on the same line
- // Wrapped at the colon and indented with four spaces
- MyClass::MyClass(int var)
- : someVar_(var), someOtherVar_(var + 1) // Good: Add a space after the comma.
- {
- DoSomething();
- }
-
- // If an initialization list needs to be placed in multiple lines, put each member on a separate line and align between lines.
- MyClass::MyClass(int var)
- someVar(var), // Four spaces of indentation.
- someOtherVar_(var + 1)
- {
- DoSomething();
- }
-
-Comments
-********
-
-Generally, clear architecture and good naming are recommended to improve code readability, and comments are provided only when necessary.
-Comments are used to help readers quickly understand code. Therefore, **comments should be provided for the sake of readers**.
-
-Comments must be concise, clear, and unambiguous, ensuring that information is complete and not redundant.
-
-**Comments are as important as code**.
-When writing a comment, you need to step into the reader’s shoes and use comments to express what the reader really needs. Comments are used to express the function and intention of code, rather than
-repeating code.
-When modifying the code, ensure that the comments are consistent with the modified code. It is not polite to modify only code and keep the old comments, which will undermine the consistency between code and
-comments, and may confuse or even mislead readers.
-
-Comments should be made in English.
-
-Comment Style
-=============
-
-In C++ code, both ``/* */`` and ``//`` can be used for commenting.
-Comments can be classified into different types, such as file header comments, function header comments, and code comments. This is based on their purposes and positions.
-Comments of the same type must keep a consistent style.
-
-Note: Example code in this document uses comments in the ``//`` format
-only to better describe the rules and recommendations. This does not
-mean this comment format is better.
-
-File Header Comments
-====================
-
-Rule 4.2.1 File header comments must contain the copyright notice.
-------------------------------------------------------------------
-
-/ Copyright (c) 2020 Huawei Device Co., Ltd. \* Licensed under the
-Apache License, Version 2.0 (the “Licenseâ€); \* you may not use this
-file except in compliance with the License. \* You may obtain a copy of
-the License at http://www.apache.org/licenses/LICENSE-2.0 Unless
-required by applicable law or agreed to in writing, software \*
-distributed under the License is distributed on an “AS IS†BASIS, \*
-WITHOUT WARRANTIES OR CONDITIONS OF ANY KIND, either express or implied.
-\* See the License for the specific language governing permissions and
-\* limitations under the License. \*/
-
-Function Header Comments
-========================
-
-Rule 4.3.1 Function header comments with no content are forbidden.
-------------------------------------------------------------------
-
-Not all functions need function header comments. For information that
-cannot be described by function signatures, add function header
-comments.
-
-Function header comments are placed above the function declaration or
-definition. Use one of the following styles: Use ‘//’ to start the
-function header.
-
-.. code:: cpp
-
- // Single-line function header
- int Func1(void);
-
- // Multi-line function header
- // Second line
- int Func2(void);
-
-Use ``/* */`` to start the function header.
-
-.. code:: cpp
-
- /* Single-line function header */
- int Func1(void);
-
- /*
- * Another single-line function header
- */
- int Func2(void);
-
- /*
- * Multi-line function header
- * Second line
- */
- int Func3(void);
-
-Use function names to describe functions, and add function header
-comments if necessary. Do not write useless or redundant function
-headers. Do not write empty function headers with no content.
-
-The function header comment content will depend on the function and
-includes but is not limited to: a function description, return value,
-performance constraints, usage comments, memory conventions, algorithm
-implementation, reentering requirements. In the function interface
-declaration in the external header file, the function header comment
-should clearly describe important and useful information.
-
-Good example:
-
-.. code:: cpp
-
- /*
- * The number of written bytes is returned. If -1 is returned, the write operation failed.
- * Note that the memory buffer should be released by the caller.
- */
- int WriteString(const char *buf, int len);
-
-Bad example:
-
-.. code:: cpp
-
- /*
- * Function name: WriteString
- * Function: Write a character string.
- * Parameters:
- * Return value:
- */
- int WriteString(const char *buf, int len);
-
-Problems:
-
-- The ‘Parameters’ and ‘Return value’ have no content.
-- The function name is redundant.
-- The most import thing, that is, who needs to release the buffer, is
- not clearly stated.
-
-Code Comments
-=============
-
-Rule 4.4.1 Code comments are placed above or on the right of the corresponding code.
-------------------------------------------------------------------------------------
-
-Rule 4.4.2 There must be a space between the comment character and the comment content. At least one space is required between the comment and code if the comment is placed to the right of code.
---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-
-Comments placed above code should be indented the same as that of the
-code. Use one of the following styles: Use “//â€.
-
-.. code:: cpp
-
-
- // Single-line comment
- DoSomething();
-
- // Multi-line comment
- // Second line
- DoSomething();
-
-Use ``/* */``.
-
-.. code:: cpp
-
- /* Single-line comment */
- DoSomething();
-
- /*
- * Multi-line comment in another mode
- * Second line
- */
- DoSomething();
-
-Leave at least one space between the code and the comment on the right.
-It is recommended that no more than four spaces be left. You can use the
-Tab key to indent 1–4 spaces.
-
-Select and use one of the following styles:
-
-.. code:: cpp
-
- int foo = 100; // Comment on the right
- int bar = 200; /* Comment on the right */
-
-It is more appealing sometimes when the comment is placed on the right
-of code and the comments and code are aligned vertically. After the
-alignment, ensure that the comment is 1–4 spaces away from the widest
-line of code. For example:
-
-.. code:: cpp
-
- const int A_CONST = 100; /* Related comments of the same type can be aligned vertically. */
- const int ANOTHER_CONST = 200; /* Leave spaces after code to align comments vertically. */
-
-When the comment on the right exceeds the line width, consider placing
-the comment above the code.
-
-Rule 4.4.3 Delete unused code segments. Do not comment them out.
-----------------------------------------------------------------
-
-Code that is commented out cannot be maintained. If you attempt to
-restore the code, it is very likely to introduce ignorable defects. The
-correct method is to delete unnecessary code directly. If necessary,
-consider porting or rewriting the code.
-
-Here, commenting out refers to the removal of code from compilation
-without actually deleting it. This is done by using /\* \*/, //, #if 0,
-#ifdef NEVER_DEFINED, and so on.
-
-Recommendation 4.4.1 Delivered code cannot contain a TODO/TBD/FIXME comment.
-----------------------------------------------------------------------------
-
-TODO/TBD comments are used to describe required improvements and
-supplements. FIXME comments are used to describe defects that need
-fixing. They should have a standardized style, which facilitates text
-search. For example:
-
-.. code:: cpp
-
- // TODO(<author-name>): XX
- // FIXME: XX
-
-Header Files
-************
-
-Header File Responsibility
-==========================
-
-A header file is an external interface of a module or file. The design
-of a header file shows most of the system design. The interface
-declaration for most functions is more suitable placed in the header
-file, but implementation (except inline functions) cannot be placed in
-the header file. Functions, macros, enumerations, and structure
-definitions that need to be used in .cpp files cannot be placed in the
-header file. The header responsibility should be simple. An overly
-complex header file will make dependencies complex and cause long
-compilation times.
-
-Recommendation 5.1.1 Each .cpp file should have a .h file with the same name. It should be used to declare the classes and interfaces that need to be exposed externally.
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-
-Generally, each .cpp file has a corresponding .h file. This .cpp file is
-used to store the function declarations, macro definitions, and class
-definitions that are to be exposed. If a .cpp file does not need to open
-any interface externally, it should not exist. Exception: **An entry
-point (for example, the file where the main function is located), unit
-tests, and dynamic libraries**
-
-For example:
-
-.. code:: cpp
-
- // Foo.h
-
- #ifndef FOO_H
- #define FOO_H
-
- class Foo {
- public:
- Foo();
- void Fun();
-
- private:
- int value_;
- };
-
- #endif
-
-.. code:: cpp
-
- // Foo.cpp
- #include "Foo.h"
-
- namespace { // Good: The declaration of the internal function is placed in the header of the .cpp file, and has been limited to the unnamed namespace or static scope.
- void Bar()
- {
- }
- }
-
- ...
-
- void Foo::Fun()
- {
- Bar();
- }
-
-Header File Dependency
-======================
-
-Rule 5.2.1 Header file cyclic dependency is forbidden.
-------------------------------------------------------
-
-An example of cyclic dependency (also known as circular dependency) is: a.h contains b.h, b.h contains c.h, and c.h contains a.h. If any of these header files is modified, all code containing a.h, b.h, and
-c.h needs to be recompiled.
-For a unidirectional dependency, for example if: a.h contains b.h, b.h contains c.h, and c.h does not contain any header file, modifying a.h does not mean that we need to recompile the source code for b.h or
-c.h.
-
-The cyclic dependency of header files reflects an obviously unreasonable architecture design, which can be avoided through optimization.
-
-Rule 5.2.2 Header files should have #define guards to prevent multiple inclusion.
----------------------------------------------------------------------------------
-
-To prevent header files from being included multiple times, all header files should be protected by #define. Do not use #pragma once.
-
-When defining a protection character, comply with the following rules:
-The protection character uses a unique name. 2) Do not place code or comments (except for file header comments) before or after the protected
-part.
-
-Example: Assume that the timer.h file of the timer module is in the timer/include/timer.h directory. Perform the following operations to safeguard the timer.h file:
-
-.. code:: cpp
-
- #ifndef TIMER_INCLUDE_TIMER_H
- #define TIMER_INCLUDE_TIMER_H
- ...
- #endif
-
-Rule 5.2.3 It is prohibited to reference external function interfaces and variables in extern declaration mode.
----------------------------------------------------------------------------------------------------------------
-
-Interfaces provided by other modules or files can be used only by
-including header files. Using external function interfaces and variables
-in extern declaration mode may cause inconsistency between declarations
-and definitions when external interfaces are changed. In addition, this
-kind of implicit dependency may cause architecture corruption.
-
-Cases that do not comply with specifications:
-
-// a.cpp content
-
-.. code:: cpp
-
- extern int Fun(); // Bad: Use external functions in extern mode.
-
- void Bar()
- {
- int i = Fun();
- ...
- }
-
-// b.cpp content
-
-.. code:: cpp
-
- int Fun()
- {
- // Do something
- }
-
-Should be changed to:
-
-// a.cpp content
-
-.. code:: cpp
-
- #include "b.h" // Good: Use the interface provided by other .cpp by including its corresponding header file.
-
- void Bar()
- {
- int i = Fun();
- ...
- }
-
-// b.h content
-
-.. code:: cpp
-
- int Fun();
-
-// b.cpp content
-
-.. code:: cpp
-
- int Fun()
- {
- // Do something
- }
-
-In some scenarios, if internal functions need to be referenced with no intrusion to the code, the extern declaration mode can be used. For
-example: When performing unit testing on an internal function, you can use the extern declaration to reference the tested function. When a
-function needs to be stubbed or patched, the function can be declared using extern.
-
-Rule 5.2.4 Do not include header files in extern “Câ€.
------------------------------------------------------
-
-If a header file is included in extern “Câ€, extern “C†may be nested.
-Some compilers restrict the nesting of extern “Câ€. If there are too many
-nested layers, compilation errors may occur.
-
-When C and C++ programmings are used together and if extern “C†includes
-a header file, the original intent behind the header file may be
-hindered. For example, when the link specifications are modified
-incorrectly.
-
-For example, assume that there are two header files a.h and b.h.
-
-// a.h content
-
-.. code:: cpp
-
- ...
- #ifdef __cplusplus
- void Foo(int);
- #define A(value) Foo(value)
- #else
- void A(int)
- #endif
-
-// b.h content
-
-.. code:: cpp
-
- ...
- #ifdef __cplusplus
- extern "C" {
- #endif
-
- #include "a.h"
- void B();
-
- #ifdef __cplusplus
- }
- #endif
-
-Using the C++ preprocessor to expand b.h, the following information is
-displayed:
-
-.. code:: cpp
-
- extern "C" {
- void Foo(int);
- void B();
- }
-
-According to the author of a.h, the function Foo is a C++ free function
-following the “C++†link specification. However, because
-``#include "a.h"`` is placed inside ``extern "C"`` in b.h, the link
-specification of function Foo is changed incorrectly.
-
-Exception: In the C++ compilation environment, if you want to reference
-the header file of pure C, the C header files should not contain
-``extern "C"``. The non-intrusive approach is to include the C header
-file in ``extern "C"``.
-
-Recommendation 5.2.1 Use ``#include`` instead of a forward declaration to include header files.
------------------------------------------------------------------------------------------------
-
-A forward declaration is for the declaration of classes, functions, and
-templates and is not meant for its definition.
-
-* Advantages:
-
- * Forward declarations can save compilation time. Redundant ``#include``\ statements force the compiler to expand more files and process more input.
- * Forward declarations can save unnecessary recompilation time. The use of #include will force your code to be recompiled multiple times due to
- unrelated changes in header files.
-
-* Disadvantages:
-
- * Forward declarations hide dependency relationship. When a header file is modified, user code will skip the necessary recompilation process.
- * A forward declaration may be broken by subsequent changes to the library. Forward declarations of functions and templates sometimes prevent
- header file developers from changing APIs. For example, widening a formal parameter type, adding a template parameter with a default value, and so
- on.
- * Forward declaration of symbols from the namespace ``std::`` is seen as undefined behavior (as specified in the C++ 11 standard specification).
- * Forward declaration of multiple symbols from a header file can be more verbose than simply including (#include) the header.
- * Structuring code only for forward declaration (for example, using pointer members instead of object members) can make the code more
- complex and slower.
- * It is difficult to determine whether a forward declaration or ``#include`` is needed. In some scenarios, replacing ``#include``
- with a forward declaration may cause unexpected results.
-
-Therefore, we should avoid using forward declarations as much as possible. Instead, we use the #include statement to include a header
-file and ensure dependency.
-
-Scopes
-******
-
-Namespaces
-==========
-
-Recommendation 6.1.1 For code that does not need to be exported from the .cpp file, you are advised to use an unnamed namespace for encapsulation or use static to modify the variables, constants, or functions that need hiding.
-----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-
-In the C++ 2003 standard, using static to modify the external availability of functions and variables was marked as deprecated.
-Therefore, unnamed namespaces are the recommended method.
-
-Main Reasons:
-
-#. There are too many meanings for static in C++: static function member variable, static member function, static global variable, and static function local variable. Each of them has specialprocessing.
-#. Static can only be used to define variables, constants, and functions that are not referenced outside the current .cpp file, while namespaces can also be used to encapsulate types.
-#. Use a namespace to control the scope instead of using both static and namespaces.
-#. Unnamed namespaces can be used to instantiate templates rather than functions modified by the static keyword.
-
-Do not use unnamed namespaces or static in header files.
-
-.. code:: cpp
-
- // Foo.cpp
-
- namespace {
- const int MAX_COUNT = 20;
- void InternalFun(){};
- }
-
- void Foo::Fun()
- {
- int i = MAX_COUNT;
-
- InternalFun();
- }
-
-Rule 6.1.1 Do not use “using†to import namespace in a header file or before #include statements.
--------------------------------------------------------------------------------------------------
-
-Note: Using “using†to import namespace will affect any subsequent code
-and may cause symbol conflicts. Example:
-
-.. code:: cpp
-
- // Header file a.h
- namespace NamespaceA {
- int Fun(int);
- }
-
-.. code:: cpp
-
- // Header file b.h
- namespace NamespaceB {
- int Fun(int);
- }
-
- using namespace NamespaceB;
-
- void G()
- {
- Fun(1);
- }
-
-.. code:: cpp
-
- // Source code a.cpp
- #include "a.h"
- using namespace NamespaceA;
- #include "b.h"
-
- void main()
- {
- G(); // "using namespace NamespaceA" before #include "b.h", will cause conflicts when calling NamespaceA::Fun and NamespaceB::Fun.
- }
-
-Using “using†to import a symbol or define an alias in a header file is
-allowed in customized namespaces of modules, but is prohibited in the
-global namespace.
-
-.. code:: cpp
-
- // foo.h
-
- #include <fancy/string>
- using fancy::string; // Bad: It is prohibited to import symbols to the global namespace.
-
- namespace Foo {
- using fancy::string; // Good: Symbols can be imported in customized namespaces of modules.
- using MyVector = fancy::vector; // Good: In C++11, aliases can be defined in customized namespaces.
- }
-
-Global Functions and Static Member Functions
-============================================
-
-Recommendation 6.2.1 Use namespaces to manage global functions. If global functions are closely tied to a class, you can use static member functions.
------------------------------------------------------------------------------------------------------------------------------------------------------
-
-Note: Placing non-member functions in a namespace avoids polluting the
-global scope. Do not use “class + static member function†to simply
-manage global functions. If a global function is closely tied to a
-class, it can be used as a static member function of the class.
-
-If you need to define some global functions for a .cpp file, use unnamed
-namespaces for management.
-
-.. code:: cpp
-
- namespace MyNamespace {
- int Add(int a, int b);
- }
-
- class File {
- public:
- static File CreateTempFile(const std::string& fileName);
- };
-
-Global Constants and Static Member Constants
-============================================
-
-
-Recommendation 6.3.1 Use namespaces to manage global constants. If global constants are closely tied to a class, you can use static member constants.
------------------------------------------------------------------------------------------------------------------------------------------------------
-
-Note: Placing global constants in a namespace avoids polluting the
-global scope. Do not use “class + static member constant†to simply
-manage global constants. If a global constant is closely tied to a
-class, it can be used as a static member constant of the class.
-
-If you need to define some global constants only for a .cpp file, use
-unnamed namespaces for management.
-
-.. code:: cpp
-
- namespace MyNamespace {
- const int MAX_SIZE = 100;
- }
-
- class File {
- public:
- static const std::string SEPARATOR;
- };
-
-Global Variables
-================
-
-Recommendation 6.4.1 Do not use global variables. Use the singleton pattern instead.
-------------------------------------------------------------------------------------
-
-Note: Global variables can be modified and read, which results in data
-coupling between production code and the global variables.
-
-.. code:: cpp
-
- int g_counter = 0;
-
- // a.cpp
- g_counter++;
-
- // b.cpp
- g_counter++;
-
- // c.cpp
- cout << g_counter << endl;
-
-Singleton
-
-.. code:: cpp
-
- class Counter {
- public:
- static Counter& GetInstance()
- {
- static Counter counter;
- return counter;
- } // Simple example of a singleton implementation
-
- void Increase()
- {
- value_++;
- }
-
- void Print() const
- {
- std::cout << value_ << std::endl;
- }
-
- private:
- Counter() : value_(0) {}
-
- private:
- int value_;
- };
-
- // a.cpp
- Counter::GetInstance().Increase();
-
- // b.cpp
- Counter::GetInstance().Increase();
-
- // c.cpp
- Counter::GetInstance().Print();
-
-After the singleton is implemented, there is a unique global instance, which can functions as a global variable. However, the singleton
-provides better encapsulation.
-
-Exception: In some cases, the scope of a global variable is contained inside a module. Multiple instances of the same global variable may
-exist, and each module holds one copy. In this case, a singleton cannot be used as it is limited to one instance.
-
-Classes
-=======
-
-Constructors, Copy/Move Constructors, Copy/Move Assignment Operators, and Destructors
--------------------------------------------------------------------------------------
-
-| Constructors, copy/move constructors, copy/move assignment operators,
- and destructors provide lifetime management methods for objects. -
- Constructor: ``X()`` - Copy constructor: ``X(const X&)`` - Copy
- assignment operator: ``operator=(const X&)``
-| - Move constructor: ``X (X&&)`` *Provided in versions later than C++
- 11*. - Move assignment operator: ``operator=(X&&)`` *Provided in
- versions later than C++ 11*. - Destructor: ``~X()``
-
-Rule 7.1.1 The member variables of a class must be initialized explicitly.
---------------------------------------------------------------------------
-
-Note: If a class has members but no constructor and a default
-constructor is defined, the compiler will automatically generate a
-constructor, but it will not initialize member variables. The content of
-each object is uncertain.
-
-Exception: - If the member variables in a class have a default constructor, explicit initialization is not required.
-
-Example: The following code has no constructor, and private data members cannot be initialized:
-
-.. code:: cpp
-
- class Message {
- public:
- void ProcessOutMsg()
- {
- //…
- }
-
- private:
- unsigned int msgID_;
- unsigned int msgLength_;
- unsigned char* msgBuffer_;
- std::string someIdentifier_;
- };
-
- Message message; // The message member is not initialized.
- message.ProcessOutMsg(); // Potential risks exist in subsequent use.
-
- // Therefore, it is necessary to define a default constructor as follows:
- class Message {
- public:
- Message() : msgID_(0), msgLength_(0), msgBuffer_(NULL)
- {
- }
-
- void ProcessOutMsg()
- {
- // …
- }
-
- private:
- unsigned int msgID_;
- unsigned int msgLength_;
- unsigned char* msgBuffer_;
- std::string someIdentifier; // The member variable has a default constructor. Therefore, explicit initialization is not required.
- };
-
-Recommendation 7.1.1 Initialization during declaration (C++ 11) and initialization using the constructor initialization list are preferred for member variables.
-----------------------------------------------------------------------------------------------------------------------------------------------------------------
-
-Note: Initialization during declaration (C++11) is preferred because
-initialized values of member variables can be easily understood. If
-initialized values of certain member variables are relevant to
-constructors, or C++ 11 is not supported, the constructor initialization
-list is used preferentially to initialize these member variables.
-Compared with the assignment statements in constructors, code of the
-constructor initialization list is simpler and has higher performance,
-and can be used to initialize constant and reference members.
-
-.. code:: cpp
-
- class Message {
- public:
- Message() : msgLength(0) { // Good: The constructor initialization list is preferred.
- {
- msgBuffer = NULL; // Bad: Values cannot be assigned in constructors.
- }
-
- private:
- unsigned int msgID{0}; // Good: Used in C++11.
- unsigned int msgLength_;
- unsigned char* msgBuffer_;
- };
-
-Rule 7.1.2 Declare single-parameter constructors as explicit to prevent implicit conversion.
---------------------------------------------------------------------------------------------
-
-Note: If a single-parameter constructor is not declared as explicit, it
-will become an implicit conversion function. Example:
-
-.. code:: cpp
-
- class Foo {
- public:
- explicit Foo(const string& name): name_(name)
- {
- }
- private:
- string name_;
- };
-
-
- void ProcessFoo(const Foo& foo){}
-
- int main(void)
- {
- std::string test = "test";
- ProcessFoo(test); // Compiling failed.
- return 0;
- }
-
-The preceding code fails to be compiled because the parameter required by ``ProcessFoo`` is of the Foo type, which mismatch with the input string type.
-
-If the explicit keyword of the Foo constructor is removed, implicit conversion is triggered and a temporary Foo object is generated when ``ProcessFoo`` is called with the string parameter. Usually, this
-implicit conversion is confusing and bugs are apt to be hidden, due to unexpected type conversion. Therefore, single-parameter constructors require explicit declaration.
-
-Rule 7.1.3 If copy/move constructors and copy/move assignment operators are not needed, clearly prohibit them.
---------------------------------------------------------------------------------------------------------------
-
-Note: If users do not define it, the compiler will generate copy constructors and copy assignment operators, move constructors and move assignment operators (move semantic functions will be available in versions later than C++ 11). If we do not use copy constructors or copy
-assignment operators, explicitly delete them.
-
-Set copy constructors or copy assignment operators to private and do not implement them.
-
-.. code:: cpp
-
- class Foo {
- private:
- Foo(const Foo&);
- Foo& operator=(const Foo&);
- };
-
-Use delete provided by C++ 11. For details, see Rule 10.1.3 in chapter 10 Modern C++ Features.
-
-Rule 7.1.4 Copy constructors and copy assignment operators should be implemented or forbidden together.
--------------------------------------------------------------------------------------------------------
-
-Both copy constructors and copy assignment operators provide copy semantics. They should be implemented or hidden together.
-
-.. code:: cpp
-
- // The copy constructor and the copy assignment operator are implemented together.
- class Foo {
- public:
- ...
- Foo(const Foo&);
- Foo& operator=(const Foo&);
- ...
- };
-
- // The copy constructor and the copy assignment operator are both set to default, as supported by C++ 11.
- class Foo {
- public:
- Foo(const Foo&) = default;
- Foo& operator=(const Foo&) = default;
- };
-
- // The copy constructor and the copy assignment operator are hidden together. You should use the delete keyword if C++11 features are available.
- class Foo {
- private:
- Foo(const Foo&);
- Foo& operator=(const Foo&);
- };
-
-Rule 7.1.5 Move constructors and move assignment operators should be implemented or hidden together.
-----------------------------------------------------------------------------------------------------
-
-The move operation is added in C++ 11. If a class is required to support
-the move operation, move constructors and move assignment operators need
-to be implemented.
-
-Both move constructors and move assignment operators provide move
-semantics. They should be implemented or hidden together.
-
-.. code:: cpp
-
- // The copy constructor and the copy assignment operator are implemented together.
- class Foo {
- public:
- ...
- Foo(Foo&&);
- Foo& operator=(Foo&&);
- ...
- };
-
- // The copy constructor and the copy assignment operator are both set to default, as supported by C++ 11.
- class Foo {
- public:
- Foo(Foo&&) = default;
- Foo& operator=(Foo&&) = default;
- };
-
- // The copy constructor and the copy assignment operator are hidden together. You should use the delete keyword if C++11 features are available.
- class Foo {
- public:
- Foo(Foo&&) = delete;
- Foo& operator=(Foo&&) = delete;
- };
-
-Rule 7.1.6 It is prohibited to call virtual functions in constructors and destructors.
---------------------------------------------------------------------------------------
-
-Note: Calling a virtual function of the current object in a constructor
-or destructor will cause behaviors of non-polymorphism. In C++, a base
-class constructs only one complete object at a time.
-
-Example: Base indicates the base class, and Sub indicates the derived
-class.
-
-.. code:: cpp
-
- class Base {
- public:
- Base();
- virtual void Log() = 0; // Different derived classes call different log files.
- };
-
- Base::Base() // Base class constructor
- {
- Log(); // Call the virtual function log.
- }
-
- class Sub : public Base {
- public:
- virtual void Log();
- };
-
-When running the following statement: ``Sub sub;`` The constructor of
-the derived class is executed first. However, the constructor of the
-base class is called first. Because the constructor of the base class
-calls the virtual function log, the log is in the base class version.
-The derived class is constructed only after the base class is
-constructed. As a result, behaviors of non-polymorphism are caused. This
-also applies to destructors.
-
-Inheritance
-===========
-
-Rule 7.2.1 Destructors of a base class should be declared as virtual.
----------------------------------------------------------------------
-
-Note: Destructors of the derived class can be called during polymorphism
-invocation only when destructors of the base class are virtual.
-
-Example: There will be memory leak if destructors of the base class are
-not declared as virtual.
-
-.. code:: cpp
-
- class Base {
- public:
- virtual std::string getVersion() = 0;
-
- ~Base()
- {
- std::cout << "~Base" << std::endl;
- }
- };
-
-.. code:: cpp
-
- class Sub : public Base {
- public:
- Sub() : numbers_(NULL)
- {
- }
-
- ~Sub()
- {
- delete[] numbers_;
- std::cout << "~Sub" << std::endl;
- }
-
- int Init()
- {
- const size_t numberCount = 100;
- numbers_ = new (std::nothrow) int[numberCount];
- if (numbers_ == NULL) {
- return -1;
- }
-
- ...
- }
-
- std::string getVersion()
- {
- return std::string("hello!");
- }
- private:
- int* numbers_;
- };
-
-.. code:: cpp
-
- int main(int argc, char* args[])
- {
- Base* b = new Sub();
-
- delete b;
- return 0;
- }
-
-Because destructors of the base class are not declared as virtual, only destructors of the base class are called when an object is destroyed.
-Destructors of the derived class Sub are not called. As a result, a memory leak occurs.
-
-Rule 7.2.2 Do not use default parameter values for virtual functions.
----------------------------------------------------------------------
-
-Note: In C++, virtual functions are dynamically bound, but the default
-parameters of functions are statically bound during compilation. This
-means that the function you finally execute is a virtual function that
-is defined in the derived class but uses the default parameter value in
-the base class. To avoid confusion and other problems caused by
-inconsistent default parameter declarations during overriding of virtual
-functions, it is prohibited to declare default parameter values for all
-virtual functions. Example: The default value of parameter “text†of the
-virtual function “Display†is determined at compilation time instead of
-runtime, which does not fit with polymorphism.
-
-.. code:: cpp
-
- class Base {
- public:
- virtual void Display(const std::string& text = "Base!")
- {
- std::cout << text << std::endl;
- }
-
- virtual ~Base(){}
- };
-
- class Sub : public Base {
- public:
- virtual void Display(const std::string& text = "Sub!")
- {
- std::cout << text << std::endl;
- }
-
- virtual ~Sub(){}
- };
-
- int main()
- {
- Base* base = new Sub();
- Sub* sub = new Sub();
-
- ...
-
- base->Display(); // The program output is as follows: Base! The expected output is as follows: Sub!
- sub->Display(); // The program output is as follows: Sub!
-
- delete base;
- delete sub;
- return 0;
- };
-
-Rule 7.2.3 Do not redefine inherited non-virtual functions.
------------------------------------------------------------
-
-Note: Non-virtual functions cannot be dynamically bound (only virtual
-functions can be dynamically bound). You can obtain the correct result
-by operating on the pointer of the base class.
-
-Example:
-
-.. code:: cpp
-
- class Base {
- public:
- void Fun();
- };
-
- class Sub : public Base {
- public:
- void Fun();
- };
-
- Sub* sub = new Sub();
- Base* base = sub;
-
- sub->Fun(); // Call Fun of the derived class.
- base->Fun(); // Call Fun of the base class.
- //...
-
-Multiple Inheritance
-====================
-
-In the actual development process, multiple inheritance is seldom used because the following typical problems may occur:
-
-#. Data duplication and name ambiguity caused by “diamond†inheritance. C++ introduces virtual inheritance to solve these problems.
-#. In addition to “diamond†inheritance, names of multiple base classes may also conflict with each other, resulting in name ambiguity.
-#. If a derived class needs to be extended or needs to override methods of multiple base classes, the responsibilities of the derived classes are
- unclear and semantics are muddled.
-#. Compared with delegation, inheritance is seen as white box reuse, that is, a derived class can access the protected members of the base class,
- which leads to more coupling. Multiple inheritance, due to the coupling of multiple base classes, leads to even more coupling.
-
-Multiple inheritance has the following advantages:
-
-Multiple inheritance provides a simpler method for assembling and reusing multiple interfaces or classes. Therefore, multiple inheritance can be used only in the following cases:
-
-Recommendation 7.3.1 Use multiple inheritance to implement interface separation and multi-role combination.
------------------------------------------------------------------------------------------------------------
-
-If a class requires multiple interfaces, combine multiple separated interfaces by using multiple inheritance. This is similar to the Traits
-mixin of the Scala language.
-
-.. code:: cpp
-
- class Role1 {};
- class Role2 {};
- class Role3 {};
-
- class Object1 : public Role1, public Role2 {
- // ...
- };
-
- class Object2 : public Role2, public Role3 {
- // ...
- };
-
-The C++ standard library has a similar implementation example:
-
-.. code:: cpp
-
- class basic_istream {};
- class basic_ostream {};
-
- class basic_iostream : public basic_istream, public basic_ostream {
-
- };
-
-Overloading
------------
-
-Overload operators should be used when there are sufficient reasons, and they do not change the original perception of the operators.
-For example, do not use the plus sign (+) to perform subtraction. Operator overloading can make code more intuitive but has some disadvantages:
-
-* It is often mistaken that the operation is as fast as a built-in operator, which has no performance degradation.
-* There is no naming to aid debugging. It is more convenient to search by function name than by operator.
-* Overloading operators can cause confusion if behavior definitions are not intuitive (for example, if the “+†operator is used for subtraction).
-* The implicit conversion caused by the overloading of assignment operators may lead to entrenched bugs. Functions such as Equals () and CopyFrom ()
- can be defined to replace the = and == operators.
-
-Functions
-*********
-
-Function Design
-===============
-
-Rule 8.1.1 Avoid long functions and ensure that each function contains no more than 50 lines (non-null and non-comment).
-------------------------------------------------------------------------------------------------------------------------
-
-A function should be displayed on one screen (no longer than 50 lines). It should do only one thing, and do it well.
-
-Long functions often mean that the functions are too complex to implement in more than one function, or overly detailed but not further
-abstracted.
-
-Exception: Some algorithms may be longer than 50 lines due to algorithm convergence and functional comprehensiveness.
-
-Even if a long function works very well now, once someone modifies it, new problems may occur. It might even cause bugs that are difficult to
-find. It is recommended that you split a long function into several functions that are simpler and easier to manage, facilitating comprehension and modification.
-
-Inline Functions
-================
-
-Recommendation 8.2.1 An inline function cannot exceed 10 lines.
----------------------------------------------------------------
-
-**Note**: An inline function has the same characteristics of a normal function. The difference between an inline function and a normal function lies in the processing of function calls. When a general function is called, the program execution right is transferred to the
-called function, and then returned to the function that calls it. When an inline function is called, the invocation expression is replaced with an inline function body.
-
-Inline functions are only suitable for small functions with only 1-10 lines. For a large function that contains many statements, the function call and return overheads are relatively trivial and do not need the
-help of an inline function. Most compilers may abandon the inline mode and use the common method to call the function.
-
-If an inline function contains complex control structures, such as loop, branch (switch), and try-catch statements, the compiler may regard the function as a common function. **Virtual functions and recursive
-functions cannot be used as inline functions**.
-
-Function Parameters
-===================
-
-Recommendation 8.3.1 Use a reference instead of a pointer for function parameters.
-----------------------------------------------------------------------------------
-
-**Note**: A reference is more secure than a pointer because it is not empty and does not point to other targets. Using a reference stops the need to check for illegal null pointers.
-
-If a product is being developed for an older platform, the processing used by the old platform is preferred. Use const to avoid parameter modification, so that readers can clearly know that a parameter is not going to be modified. This greatly enhances code readability.
-
-Exception: When the input parameter is an array with an unknown compile-time length, you can use a pointer instead of a reference.
-
-Recommendation 8.3.2 Use strongly typed parameters. Do not use void*.
----------------------------------------------------------------------
-
-While different languages have their own views on strong typing and weak typing, it is generally believed that C and C++ are strongly typed languages. Since we use such a strongly typed language, we should keep to this style. An advantage of this is the compiler can find type mismatch problems at the compilation stage.
-
-Using strong typing helps the compiler find more errors for us. Pay attention to the usage of the FooListAddNode function in the following code:
-
-.. code:: cpp
-
- struct FooNode {
- struct List link;
- int foo;
- };
-
- struct BarNode {
- struct List link;
- int bar;
- }
-
- void FooListAddNode(void *node) // Bad: Here, the void * type is used to transfer parameters.
- {
- FooNode *foo = (FooNode *)node;
- ListAppend(&g_FooList, &foo->link);
- }
-
- void MakeTheList()
- {
- FooNode *foo = NULL;
- BarNode *bar = NULL;
- ...
-
- FooListAddNode(bar); // Wrong: In this example, the foo parameter was supposed to be transferred, but the bar parameter is accidentally transferred instead. However, no error is reported.
- }
-
-#. You can use a template function to change the parameter type.
-#. A base class pointer can be used to implement this according to
- polymorphism.
-
-Recommendation 8.3.3 A function can have a maximum of five parameters.
-----------------------------------------------------------------------
-
-If a function has too many parameters, it is apt to be affected by external changes, and therefore maintenance is affected. Too many
-function parameters will also increase the testing workload.
-
-If a function has more than five parameters, you can:
-
-* Split the function.
-* Combine related parameters into a struct.
-
-Other C++ Features
-******************
-
-Constants and Initialization
-============================
-
-Unchanged values are easier to understand, trace, and analyze.
-Therefore, use constants instead of variables as much as possible. When
-defining values, use const as a default.
-
-Rule 9.1.1 Do not use macros to replace constants.
---------------------------------------------------
-
-**Note**: Macros are a simple text replacement that is completed in the
-preprocessing phase. When an error is reported, the corresponding value
-is reported. During tracing and debugging, the value is also displayed
-instead of the macro name. A macro does not support type checking and is
-insecure. A macro has no scope.
-
-.. code:: cpp
-
- #define MAX_MSISDN_LEN 20 // Bad
-
- // Use const in C++.
- const int MAX_MSISDN_LEN = 20; // Good
-
- // In versions later than C++ 11, constexpr can be used.
- constexpr int MAX_MSISDN_LEN = 20;
-
-Recommendation 9.1.1 A group of related integer constants must be defined as an enumeration.
---------------------------------------------------------------------------------------------
-
-**Note**: Enumerations are more secure than ``#define`` or
-``const int``. The compiler checks whether a parameter value is within
-the enumerated value range to avoid errors.
-
-.. code:: cpp
-
- // Good example:
- enum Week {
- SUNDAY,
- MONDAY,
- TUESDAY,
- WEDNESDAY,
- THURSDAY,
- FRIDAY,
- SATURDAY
- };
-
- enum Color {
- RED,
- BLACK,
- BLUE
- };
-
- void ColorizeCalendar(Week today, Color color);
-
- ColorizeCalendar(BLUE, SUNDAY); // Compilation error. The parameter type is incorrect.
-
- // Bad example:
- const int SUNDAY = 0;
- const int MONDAY = 1;
-
- const int BLACK = 0;
- const int BLUE = 1;
-
- bool ColorizeCalendar(int today, int color);
- ColorizeCalendar(BLUE, SUNDAY); // No error is reported.
-
-When an enumeration value needs to correspond to a specific value,
-explicit value assignment is required during declaration. Otherwise, do
-not assign explicit values. This will prevent repeated assignment and
-reduce the maintenance workload (when adding and deleting members).
-
-.. code:: cpp
-
- // Good example: Device ID defined in the S protocol. It is used to identify a device type.
- enum DeviceType {
- DEV_UNKNOWN = -1,
- DEV_DSMP = 0,
- DEV_ISMG = 1,
- DEV_WAPPORTAL = 2
- };
-
-Do not assign explicit values when enumeration is used internally, and
-only for classification.
-
-.. code:: cpp
-
- // Good example: Enumeration definition is used to identify session status in a program.
- enum SessionState {
- INIT,
- CLOSED,
- WAITING_FOR_RESPONSE
- };
-
-Try to avoid repeating enumeration values. If it is required, use the
-already defined enumeration values instead.
-
-.. code:: cpp
-
- enum RTCPType {
- RTCP_SR = 200,
- RTCP_MIN_TYPE = RTCP_SR,
- RTCP_RR = 201,
- RTCP_SDES = 202,
- RTCP_BYE = 203,
- RTCP_APP = 204,
- RTCP_RTPFB = 205,
- RTCP_PSFB = 206,
- RTCP_XR = 207,
- RTCP_RSI = 208,
- RTCP_PUBPORTS = 209,
- RTCP_MAX_TYPE = RTCP_PUBPORTS
- };
-
-Rule 9.1.2 Magic numbers cannot be used.
-----------------------------------------
-
-So-called magic numbers are numbers that are unintelligible and
-difficult to understand.
-
-Some numbers can be understood based on context. For example, the number
-12 varies in different contexts. type = 12; is not intelligible (and a
-magic number), but ``month = year * 12``; can be understood, so we
-wouldn’t really class this as a magic number. The number 0 is often seen
-as a magic number. For example, ``status = 0``; cannot truly express any
-status information.
-
-Solution: Comments can be added for numbers that are used locally. For
-the numbers that are used multiple times, you must define them as
-constants and give them descriptive names.
-
-The following cases are forbidden: No symbol is used to explain the
-meaning of a number, for example, ``const int ZERO = 0``. The symbol
-name limits the value. For example, for example,
-``const int XX_TIMER_INTERVAL_300MS = 300``. Use
-``XX_TIMER_INTERVAL_MS`` instead.
-
-Rule 9.1.3 Ensure that a constant has only one responsibility.
---------------------------------------------------------------
-
-**Note**: A constant is used for only one specific function, that is, a
-constant cannot be used for multiple purposes.
-
-.. code:: cpp
-
- // Good example: For protocol A and protocol B, the length of the MSISDN is 20.
- const unsigned int A_MAX_MSISDN_LEN = 20;
- const unsigned int B_MAX_MSISDN_LEN = 20;
-
- // Using different namespaces:
- namespace Namespace1 {
- const unsigned int MAX_MSISDN_LEN = 20;
- }
-
- namespace Namespace2 {
- const unsigned int MAX_MSISDN_LEN = 20;
- }
-
-Rule 9.1.4 Do not use memcpy_s or memset_s to initialize non-POD objects.
--------------------------------------------------------------------------
-
-**Note**: ``POD`` is short for ``Plain Old Data``, which is a concept
-introduced in the C++ 98 standard (ISO/IEC 14882, first edition,
-1998-09-01). The ``POD`` types include the original types and aggregate
-types such as ``int``, ``char``, ``float``, ``double``, ``enumeration``,
-``void``, and pointer. Encapsulation and object-oriented features cannot
-be used (for example, user-defined constructors, assignment operators,
-destructors, base classes, and virtual functions).
-
-For non-POD classes, such as class objects of non-aggregate types,
-virtual functions may exist. Memory layout is uncertain, and is related
-to the compiler. Misuse of memory copies may cause serious problems.
-
-Even if a class of the aggregate type is directly copied and compared,
-and any functions hiding information or protecting data are destroyed,
-the ``memcpy_s`` and ``memset_s`` operations are not recommended.
-
-For details about the POD type, see the appendix.
-
-Recommendation 9.1.2 Declare and initialize variables only when they are used.
-------------------------------------------------------------------------------
-
-**Note**: It is a common low-level programming error that a variable is
-not assigned an initial value before being used. Declaring and
-initializing a variable just before using it will prevent this.
-
-If all variables are declared at the beginning of a function before they
-are used, their scope covers the entire function, which may lead to the
-following problems: \* The program may become difficult to understand
-and maintain. The definition and use of variables are separated. \*
-These variables are difficult to initialize properly. At the beginning
-of a function, there is often insufficient information for variable
-initialization, and a default null value (such as 0) is often assigned
-as the initial value. If a variable is used before it is assigned a
-valid value, it will also cause errors.
-
-Following the minimization principle of variable scopes and the
-principle of proximity declaration will make it easier to read code and
-understand variable types and initial values. In particular, use
-initialization to replace declaration and then assign values.
-
-.. code:: cpp
-
- // Bad example: Declaration is separated from initialization.
- string name; // The variable is not initialized in the declaration, and a default constructor is called.
- name = "zhangsan"; // An assignment operator is called again. Declaration is separate from definition, which is difficult to understand.
-
- // Good example: Declaration and initialization are together, and easy to understand.
- string name("zhangsan"); // Invoke a constructor.
-
-.. _expressions-1:
-
-Expressions
-===========
-
-Rule 9.2.1 A variable cannot be referenced again if it is contained in an increment or decrement operation in an expression.
-----------------------------------------------------------------------------------------------------------------------------
-
-In an expression where the increment or decrement operations are
-performed on a variable, the variable cannot be referenced again. The
-result of a second referencing is not explicitly defined in C++
-standards. The results in different compilers or different versions of a
-compiler may be different. Therefore, it is recommended that an
-undefined operation sequence not be assumed.
-
-Note that the problem of operation sequence cannot be solved by using
-parentheses because this is not a priority problem.
-
-Example:
-
-.. code:: cpp
-
- x = b[i] + i++; // Bad: Whether the position of b[i] is before or after the i++ is unclear.
-
-The increment or decrement operation should be placed in a single line:
-
-.. code:: cpp
-
- x = b[i] + i;
- i++; // Good: i++ is placed in a single line.
-
-Function parameter
-
-.. code:: cpp
-
- Func(i++, i); // Bad: Whether the increment operation happens for the second parameter is unclear
-
-Good example:
-
-.. code:: cpp
-
- i++; // Good: i++ is placed in a single line.
- x = Func(i, i);
-
-Rule 9.2.2 A switch statement must have a default branch.
----------------------------------------------------------
-
-In most cases, a switch statement requires a default branch to ensure
-that there is a default action when the case tag is missing for a
-processed value.
-
-Exception: If the switch condition variables are enumerated and the case
-branch covers all values, the default branch is redundant. Because
-modern compilers can check which case branches are missing in the switch
-statement and provide an advanced warning.
-
-.. code:: cpp
-
- enum Color {
- RED = 0,
- BLUE
- };
-
- // The switch condition variables are enumerated. Therefore, you do not need to add a default branch.
- switch (color) {
- case RED:
- DoRedThing();
- break;
- case BLUE:
- DoBlueThing();
- ...
- break;
- }
-
-Recommendation 9.2.1 When comparing expressions, follow the principle that the left side tends to change and the right side tends to remain unchanged.
-------------------------------------------------------------------------------------------------------------------------------------------------------
-
-When a variable is compared with a constant, placing the constant on the
-left, for example, if (MAX == v), does not comply with standard reading
-habits and is more difficult to understand. The constant should be
-placed on the right. The expression is written as follows:
-
-.. code:: cpp
-
- if (value == MAX) {
-
- }
-
- if (value < MAX) {
-
- }
-
-There are special cases: for example, if the expression
-``if (MIN < value && value < MAX)`` is used to describe a range, the
-first half, as a constant, should be placed on the left.
-
-You do not need to worry about writing ‘==’ as ‘=’ because a compilation
-alarm will be generated for ``if (value = MAX)`` and an error will be
-reported by other static check tools. Use these tools to solve such
-writing errors and ensure that that code is readable.
-
-Recommendation 9.2.2 Use parentheses to specify the operator precedence.
-------------------------------------------------------------------------
-
-Use parentheses to specify the operator precedence. This will prevent
-program errors due to the inconsistency between default priority and the
-intended design. At the same time, it makes the code clearer and more
-readable. However, too many parentheses muddy the code, reducing
-readability. The following is a recommendation on their correct usage.
-
-For binary and ternary operators, if multiple operators are involved, parentheses should be used.
-
-.. code:: cpp
-
- x = a + b + c; /* The operator does not change, and thus parentheses are not required. */
- x = Foo(a + b, c); /* The operator does not change, and thus parentheses are not required. */
- x = 1 << (2 + 3); /* More than one operator is used and thus parentheses are required. */
- x = a + (b / 5); /* More than one operator is used and thus parentheses are required. */
- x = (a == b) ? a : (a – b); /* More than one operator is used and thus parentheses are required. */
-
-Type Casting
-============
-
-Do not use type branches to customize behaviors. Type branch
-customization behavior is prone to errors and is an obvious sign of
-attempting to compile C code using C++. This is very inflexible
-technology. If you forget to modify all branches when adding a new type
-to a compiler, you will not be notified. Use templates and virtual
-functions to let the type define itself rather than letting the calling
-side determine behavior.
-
-It is recommended that type casting be avoided. We should consider the
-data type in the code design instead of overusing type casting to solve
-type conflicts. When designing a basic type, consider the following: -
-Whether it is unsigned or signed. - Is it suitable for float or double?
-- Should you use int8, int16, int32, or int64 bit lengths?
-
-However, we cannot prohibit the use of type casting because the C++
-language is a machine-oriented programming language, involving pointer
-addresses, and we interact with various third-party or underlying APIs.
-Their type design may not be reasonable and type casting tends to occur
-in the adaptation process.
-
-Exception: When calling a function, if we do not want to process the
-result of the function, first consider whether this is your best choice.
-If you do not want to process the return value of the function, cast it
-to void.
-
-Rule 9.3.1 If type casting is required, use the type casting provided by the C++ instead of the C style.
---------------------------------------------------------------------------------------------------------
-
-**Note**:
-
-The type casting provided by C++ is more targeted, easy to read, and more secure than the C style. C++ provides the following types of casting:
-
-* Type casting:
- * ``dynamic_cast``: Used to inherit the downstream transformation of the system. ``dynamic_cast`` has the type
- check function. Design the base class and derived class to avoid using dynamic_cast for casting.
- * ``static_cast``: Similar to the C style casting, which can be used to convert a value, or to convert the pointer or reference of a derived class
- into a base class pointer or reference.
- This casting is often used to eliminate type ambiguity brought on by multiple inheritance, which is relatively safe. If it is a pure arithmetic
- conversion, use the braces as stated in the following text.
- * ``reinterpret_cast``: Used to convert irrelevant types. ``reinterpret_cast`` forces the compiler to reinterpret the memory of a certain type of objects into another type, which is an unsafe conversion. It is recommended that ``reinterpret_cast`` be used as little as possible.
- * ``const_cast``: Used to remove the ``const`` attribute of an object so that the object can be modified. You are advised to use ``const_cast`` as
- little as possible.
-
-* Arithmetic conversion: (Supported by C++ 11 and later versions) If the type information is not lost, for example, the casting from float to double,
- or from int32 to int64, the braces syntax is recommended.
-
-.. code:: cpp
-
- double d{ someFloat };
- int64_t i{ someInt32 };
-
-Recommendation 9.3.1 Avoid using ``dynamic_cast``.
---------------------------------------------------
-
-* ``dynamic_cast`` depends on the RTTI of C++ so that the programmer can identify the type of the object in C++ at run time.
-* ``dynamic_cast`` indicates that a problem has occurred in the design of the base class and derived class.The derived class destroys the
- contract of the base class and it is necessary to use ``dynamic_cast`` to convert the class to a subclass for special processing. In this case, it
- is more desirable to improve the design of the class, instead of using ``dynamic_cast`` to solve the problem.
-
-Recommendation 9.3.2 Avoid using ``reinterpret_cast``.
-------------------------------------------------------
-
-**Note**: ``reinterpret_cast`` is used to convert irrelevant types.
-Trying to use ``reinterpret_cast`` to force a type to another type
-destroys the security and reliability of the type and is an insecure
-casting method. Avoid casting between completely different types.
-
-Recommendation 9.3.3 Avoid using ``const_cast``.
-------------------------------------------------
-
-**Note**: The ``const_cast`` command is used to remove the ``const`` and
-``volatile`` properties of an object.
-
-The action of using a pointer or reference after the const_cast
-conversion to modify the const property of an object is undefined.
-
-.. code:: cpp
-
- // Bad example:
- const int i = 1024;
- int* p = const_cast<int*>(&i);
- *p = 2048; // The action is undefined.
-
-.. code:: cpp
-
- // Bad example:
- class Foo {
- public:
- Foo() : i(3) {}
-
- void Fun(int v)
- {
- i = v;
- }
-
- private:
- int i;
- };
-
- int main(void)
- {
- const Foo f;
- Foo* p = const_cast<Foo*>(&f);
- p->Fun(8); // The action is undefined.
- }
-
-Resource Allocation and Release
-===============================
-
-Rule 9.4.1 When a single object is released, delete is used. When an array object is released, delete [] is used.
------------------------------------------------------------------------------------------------------------------
-
-Note: To delete a single object, use delete; to delete an array object,
-use delete []. The reasons are as follows:
-
-* new: Apply for memory from the system and call the corresponding constructor to initialize an object.
-* new[n]: Apply for memory for n objects and call the constructor n times for each object to initialize them.
-* delete: Call the corresponding destructor first and release the memory of an object.
-* delete[]: Call the corresponding destructor for each object and release their memory.
-
-If the usage of new and delete does not match this format, the results
-are unknown. For a non-class type, new and delete will not call the
-constructor or destructor.
-
-Bad example:
-
-.. code:: cpp
-
- const int MAX_ARRAY_SIZE = 100;
- int* numberArray = new int[MAX_ARRAY_SIZE];
- ...
- delete numberArray;
- numberArray = NULL;
-
-Good example:
-
-.. code:: cpp
-
- const int MAX_ARRAY_SIZE = 100;
- int* numberArray = new int[MAX_ARRAY_SIZE];
- ...
- delete[] numberArray;
- numberArray = NULL;
-
-Recommendation 9.4.1 Use the RAII feature to trace dynamic allocation.
-----------------------------------------------------------------------
-
-Note: RAII is an acronym for Resource Acquisition Is Initialization. It
-is a simple technology that controls program resources (such as memory,
-file handle, network connections, and mutexes) by using the object
-lifecycle.
-
-The common practice is as follows: When the object is constructed, the
-resource is obtained, and the access to the resource is controlled so
-that the resource is always valid in the life cycle of the object.
-Finally, the resource is released when the object is destructed. This
-approach has two advantages: - We do not need to explicitly release
-resources. - The resources required by the object are always valid
-throughout the lifecycle of the object. This way, you do not need to
-check the validity of the resources, which simplifies logic and improves
-efficiency.
-
-In the following example, RAII removes the need for explicit release of
-mutex resources.
-
-.. code:: cpp
-
- class LockGuard {
- public:
- LockGuard(const LockType& lockType): lock_(lockType)
- {
- lock_.Aquire();
- }
-
- ~LockGuard()
- {
- lock_.Relase();
- }
-
- private:
- LockType lock_;
- };
-
-
- bool Update()
- {
- LockGuard lockGuard(mutex);
- if (...) {
- return false;
- } else {
- // Data operations
- }
-
- return true;
- }
-
-Standard Template Library
-=========================
-
-The standard template library (STL) varies between products. The
-following table lists some basic rules and suggestions for each team.
-
-Rule 9.5.1 Do not save the pointer returned by c_str () of std::string.
------------------------------------------------------------------------
-
-Note: The C++ standard does not specify that the string::c_str ()
-pointer is permanently valid. Therefore, the STL implementation used can
-return a temporary storage area and release it quickly when calling
-string::c_str (). Therefore, to ensure the portability of the program,
-do not save the result of string::c_str (). Instead, call it directly.
-
-Example:
-
-.. code:: cpp
-
- void Fun1()
- {
- std::string name = "demo";
- const char* text = name.c_str(); // After the expression ends, the life cycle of name is still in use and the pointer is valid.
-
- // If a non-const member function (such as operator[] and begin()) of the string type is invoked and the string is modified,
- // The text may become unavailable or may not be the original string.
- name = "test";
- name[1] = '2';
-
- // When the text pointer is used next time, the string is no longer "demo".
- }
-
- void Fun2()
- {
- std::string name = "demo";
- std::string test = "test";
- const char* text = (name + test).c_str(); // After the expression ends, the temporary object generated by the + operator may be destroyed, and the pointer may be invalid.
-
- // When the text pointer is used next time, it no longer points to the valid memory space.
- }
-
-Exception: In rare cases where high performance coding is required , you
-can temporarily save the pointer returned by string::c_str() to match
-the existing functions which support only the input parameters of the
-const char\* type. However, you should ensure that the lifecycle of the
-string object is longer than that of the saved pointer, and that the
-string object is not modified within the lifecycle of the saved pointer.
-
-Recommendation 9.5.1 Use std::string instead of char*.
-------------------------------------------------------
-
-Note: Using string instead of ``char*`` has the following advantages:
-* There is no need to consider the null character ’\0’at the end.
-* You can directly use operators such as ``+``, ``=``, and ``==``, and other character and string operation functions.
-* There is no need to consider memory allocation operations.This helps avoid explicit usage of ``new`` and ``delete`` and the resulting errors.
-
-Note that in some STL implementations, string is based on the
-copy-on-write policy, which causes two problems. One is that the
-copy-on-write policy of some versions does not implement thread
-security, and the program breaks down in multi-threaded environments.
-Second, dangling pointers may be caused when a dynamic link library
-transfers the string based on the copy-on-write policy, due to the fact
-that reference count cannot be reduced when the library is unloaded.
-Therefore, it is important to select a reliable STL implementation to
-ensure the stability of the program.
-
-Exception: When an API of a system or other third-party library is
-called, only ``char*`` can be used for defined interfaces. However,
-before calling the interfaces, you can use string. When calling the
-interfaces, you can use ``string::c_str()`` to obtain the character
-pointer. When a character array is allocated as a buffer on the stack,
-you can directly define the character array without using string or
-containers such as ``vector<char>``.
-
-Rule 9.5.2 Do not use auto_ptr.
--------------------------------
-
-Note: The ``std::auto_ptr`` in the STL library has an implicit ownership
-transfer behavior. The code is as follows:
-
-.. code:: cpp
-
- auto_ptr<T> p1(new T);
- auto_ptr<T> p2 = p1;
-
-After the second line of statements is executed, p1 does not point to
-the object allocated in line 1 and becomes ``NULL``. Therefore,
-``auto_ptr`` cannot be placed in any standard containers. This ownership
-transfer behavior is not expected. In scenarios where ownership must be
-transferred, implicit transfer should not be used. This often requires
-the programmer to keep extra attention on code that uses ``auto_ptr``,
-otherwise access to a null pointer will occur. There are two common
-scenarios for using auto_ptr . One is to transfer it as a smart pointer
-to outside the function that generates the auto_ptr , and the other is
-to use auto_ptr as the RAII management class. Resources are
-automatically released when the lifecycle of auto_ptr expires. In the
-first scenario, you can use std::shared_ptr instead. In the second
-scenario, you can use std::unique_ptr in the C++ 11 standard.
-std::unique_ptr is a substitute for std::auto_ptr and supports explicit
-ownership transfer.
-
-Exception: Before the C++ 11 standard is widely used, std::auto_ptr can
-be used in scenarios where ownership needs to be transferred. However,
-it is recommended that std::auto_ptr be encapsulated. The copy
-constructor and assignment operator of the encapsulation class should
-not be used in a standard container.
-
-Recommendation 9.5.2 Use the new standard header files.
--------------------------------------------------------
-
-Note: When using the standard header file of C++, use ``<cstdlib>``
-instead of ``<stdlib.h>``.
-
-Usage of const
-==============
-
-Add the keyword const before the declared variable or parameter
-(example: ``const int foo``) to prevent the variable from being tampered
-with. Add the const qualifier to the function in the class (example:
-``class Foo {int Bar (char c) const;} ;``) to make sure the function
-does not modify the status of the class member variable. const
-variables, data members, functions, and parameters ensure that the type
-detection during compilation is accurate and errors are found as soon as
-possible. Therefore, we strongly recommend that const be used in any
-possible case. Sometimes it is better to use constexpr from C++ 11 to
-define real constants.
-
-Rule 9.6.1 For formal parameters of pointer and reference types, if the parameters do not need to be modified, use const.
--------------------------------------------------------------------------------------------------------------------------
-
-Unchanging values are easier to understand, trace, and analyze.
-``const`` is used as the default option and is checked during
-compilation to make the code more secure and reliable.
-
-.. code:: cpp
-
- class Foo;
-
- void PrintFoo(const Foo& foo);
-
-Rule 9.6.2 For member functions that do not modify member variables, use const.
--------------------------------------------------------------------------------
-
-Declare the member function as ``const`` whenever possible. The access
-function should always be const. So long as the function of a member is
-not modified, the function is declared with const. When you need to
-modify data members in a virtual function, take all classes in the
-inheritance chain into account instead of only focusing on the
-implementation of a single class.
-
-.. code:: cpp
-
- class Foo {
- public:
-
- // ...
-
- int PrintValue() const // const modifies member functions and does not modify member variables.
- {
- std::cout << value_ << std::endl;
- }
-
- int GetValue() const // const modifies member functions and does not modify member variables.
- {
- return value_;
- }
-
- private:
- int value_;
- };
-
-Recommendation 9.6.1 Member variables that will not be modified after initialization should be defined as constants.
---------------------------------------------------------------------------------------------------------------------
-
-.. code:: cpp
-
- class Foo {
- public:
- Foo(int length) : dataLength_(length) {}
- private:
- const int dataLength_;
- };
-
-.. _exceptions-1:
-
-Exceptions
-==========
-
-Recommendation 9.7.1 If the function does not throw an exception, the declaration is ``noexcept``.
---------------------------------------------------------------------------------------------------
-
-**Reasons:**
-* If the function does not throw an exception, the declaration is ``noexcept``, which enables the compiler to optimize thefunction to the maximum extent, for example, reducing the execution paths and improving the efficiency of exiting when an error occurs.
-* For STL containers such as ``vector``, to ensure the interface robustness, if the ``move`` constructor of saved items is not declared as ``noexcept``, the ``copy machanism`` instead of the ``move machanism`` is used when the items are removed from the container. This would cause performance loss risks. If the function does not throw an exception, or a program does not intercept and process an exception thrown by the function, new ``noexcept`` keywords can be used to modify the function, indicating that the function does not throw an exception or the thrown exception is not intercepted or processed. For example:
-
-.. code:: cpp
-
- extern "C" double sqrt(double) noexcept; // No exceptions are thrown.
-
- // noexcept can still be used when exceptions may be thrown.
- // The exception of memory exhaustion is not processed. The function is simply declared as noexcept.
- std::vector<int> MyComputation(const std::vector<int>& v) noexcept
- {
- std::vector res = v; // Exceptions may be thrown.
- // do something
- return res;
- }
-
-**Example:**
-
-.. code:: cpp
-
- RetType Function(Type params) noexcept; // Maximized optimization
- RetType Function(Type params) noexcept; // No optimization
-
- // Declaration as noexcept for the move operation of std::vector is needed.
- class Foo1 {
- public:
- Foo1(Foo1&& other); // no noexcept
- };
-
- std::vector<Foo1> a1;
- a1.push_back(Foo1());
- a1.push_back(Foo1()); // The copy constructor is called to enable the container expansion and removal of existing items.
-
- class Foo2 {
- public:
- Foo2(Foo2&& other) noexcept;
- };
-
- std::vector<Foo2> a2;
- a2.push_back(Foo2());
- a2.push_back(Foo2()); //Triggers container expansion and invokes the move constructor to move existing elements.
-
-**Note** The default constructor, destructor, ``swap`` function, and
-``move`` operator should not throw an exception.
-
-Templates
-=========
-
-Template programming allows for extremely flexible interfaces that are
-type safe and high performance, enabling reuse of code of different
-types but with the same behavior.
-
-The disadvantages of template proramming are as follows:
-
-1. The techniques used in template programming are often obscure to
- anyone but language experts. Code that uses templates in complicated
- ways is often unreadable, and is hard to debug or maintain.
-2. Template programming often leads to extremely poor compiler time
- error messages: even if an interface is simple, complicated
- implementation details become visible when the user does something
- wrong.
-3. If the template is not properly used, the code will be over expanded
- during runtime.
-4. It is difficult to modify or refactor template code. The template
- code is expanded in multiple contexts, and it is hard to verify that
- the transformation makes sense in all of them.
-
-Therefore, it is recommended that \_\_ template programming be used only
-in a small number of basic components and basic data structure. When
-using the template programming, minimize the **complexity as much as
-possible, and** avoid exposing the template. It is better to hide
-programming as an implementation detail whenever possible, so that
-user-facing headers are readable. And you should write sufficiently
-detailed comments for code that uses templates.
-
-Macros
-======
-
-In the C++ language, it is strongly recommended that complex macros be
-used as little as possible. - For constant definitions, use ``const`` or
-``enum`` as stated in the preceding sections. - For macro functions, try
-to be as simple as possible, comply with the following principles, and
-use inline functions and template functions for replacement.
-
-.. code:: cpp
-
- // The macro function is not recommended.
- #define SQUARE(a, b) ((a) * (b))
-
- // Use the template function and inline function as a replacement.
- template<typename T> T Square(T a, T b) { return a * b; }
-
-For details about how to use macros, see the related chapters about the
-C language specifications. **Exception**: For some common and mature
-applications, for example, encapsulation for new and delete, the use of
-macros can be retained.
-
-10 Modern C++ Features
-**********************
-
-As the ISO released the C++ 11 language standard in 2011 and released
-the C++ 17 in March 2017, the modern C++ (C++ 11/14/17) adds a large
-number of new language features and standard libraries that improve
-programming efficiency and code quality. This chapter describes some
-guidelines for modern C++ use, to avoid language pitfalls.
-
-Code Simplicity and Security Improvement
-========================================
-
-Recommendation 10.1.1 Use ``auto`` properly.
---------------------------------------------
-
-**Reasons**
-
-- ``auto`` can help you avoid writing verbose, repeated type names, and
- can also ensure initialization when variables are defined.
-- The ``auto`` type deduction rules are complex and need to be read
- carefully.
-- If using ``auto`` makes the code clearer, use a specific type of it
- and use it only for local variables.
-
-**Example**
-
-.. code:: cpp
-
- // Avoid verbose type names.
- std::map<string, int>::iterator iter = m.find(val);
- auto iter = m.find(val);
-
- // Avoid duplicate type names.
- class Foo {...};
- Foo* p = new Foo;
- auto p = new Foo;
-
- // Ensure that the initialization is successful.
- int x; // The compilation is correct but the variable is not initialized.
- auto x; // The compilation failed. Initialization is needed.
-
-``auto`` type deduction may cause the following problems:
-
-.. code:: cpp
-
- auto a = 3; // int
- const auto ca = a; // const int
- const auto& ra = a; // const int&
- auto aa = ca; // int, const and reference are neglected.
- auto ila1 = { 10 }; // std::initializer_list<int>
- auto ila2{ 10 }; // std::initializer_list<int>
-
- auto&& ura1 = x; // int&
- auto&& ura2 = ca; // const int&
- auto&& ura3 = 10; // int&&
-
- const int b[10];
- auto arr1 = b; // const int*
- auto& arr2 = b; // const int(&)[10]
-
-If you do not pay attention to ``auto`` type deduction and ignore the
-reference, hard-to-find performance problems may be created.
-
-.. code:: cpp
-
- std::vector<std::string> v;
- auto s1 = v[0]; // auto deduction changes s1 to std::string in order to copy v[0].
-
-If ``auto`` is used to define an interface, such as a constant in a
-header file, the type may be changed if the developer has modified the
-value.
-
-Rule 10.1.1 Use the keyword ``override`` when rewriting virtual functions.
---------------------------------------------------------------------------
-
-**Reason:** The keyword ``override`` ensures that the function is a
-virtual function and an overridden virtual function of the base class.
-If the subclass function is different from the base class function
-prototype, a compilation alarm is generated. ``final`` also ensures that
-virtual functions are not overridden by subclasses.
-
-If you modify the prototype of a base class virtual function but forget
-to modify the virtual function overridden by the subclass, you can find
-inconsistency during compilation. You can also avoid forgetting to
-modify the overridden function when there are multiple subclasses.
-
-**Example**
-
-.. code:: cpp
-
- class Base {
- public:
- virtual void Foo();
- virtual void Foo(int var);
- void Bar();
- };
-
- class Derived : public Base {
- public:
- void Foo() const override; // Compilation failed: derived::Foo is different from that of the prototype of base::Foo and is not overridden.
- void Foo() override; // Compilation successful: derived::Foo overrode base::Foo.
- void Foo(int var) final; // Compilation successful: Derived::Foo(int) rewrites Base::Foo(int), and the derived class of Derived cannot override this function.
- void Bar() override; // Compilation failed: base::Bar is not a virtual function.
- };
-
-**Summary**
-#. When defining the virtual function for the first time based on the base class, use the keyword ``virtual``.
-#. When overriding the virtual function by a subclass in a base class, including destructors, use the keyword ``override`` or ``final`` instead of ``virtual``.
-#. For the non-virtual function, do not use ``virtual`` or ``override``.
-
-Rule: 10.1.2 Use the keyword ``delete`` to delete functions.
-------------------------------------------------------------
-
-**Reason** The ``delete`` keyword is clearer and the application scope
-is wider than a class member function that is declared as private and
-not implemented.
-
-**Example:**
-
-.. code:: cpp
-
- class Foo {
- private:
- // Whether the copy structure is deleted or not is unknown because usually only the header file is checked.
- Foo(const Foo&);
- };
-
- class Foo {
- public:
- // Explicitly delete the copy assignment operator.
- Foo& operator=(const Foo&) = delete;
- };
-
-The ``delete`` keyword can also be used to delete non-member functions.
-
-.. code:: cpp
-
- template<typename T>
- void Process(T value);
-
- template<>
- void Process<void>(void) = delete;
-
-Rule 10.1.3 Use ``nullptr`` instead of ``NULL`` or ``0``.
----------------------------------------------------------
-
-**Reason:** For a long time, C++ has not had a keyword that represents a
-null pointer, which is embarrassing:
-
-.. code:: cpp
-
- #define NULL ((void *)0)
-
- char* str = NULL; // Error: void* cannot be automatically converted to char*.
-
- void(C::*pmf)() = &C::Func;
- if (pmf == NULL) {} // Error: void* cannot be automatically converted to the pointer that points to the member function.
-
-If ``NULL`` is defined as ``0`` or ``0L``, the above problems can be
-solved.
-
-Alternatively, use ``0`` directly in places where null pointers are
-required. However, another problem occurs. The code is not clear,
-especially when ``auto`` is used for automatic deduction.
-
-.. code:: cpp
-
- auto result = Find(id);
- if (result == 0) { // Does Find() return a pointer or an integer?
- // do something
- }
-
-Literally ``0`` is of the ``int`` type (``0L`` is the ``long`` type).
-Therefore, neither ``NULL`` nor ``0`` is a pointer type. When a function
-of the pointer or integer type is overloaded, ``NULL`` or ``0`` calls
-only the overloaded pointer function.
-
-.. code:: cpp
-
- void F(int);
- void F(int*);
-
- F(0); // Call F(int) instead of F(int*).
- F(NULL); // Call F(int) instead of F(int*).
-
-In addition, ``sizeof(NULL) == sizeof(void*)`` does not always make
-sense, which is a potential risk.
-
-Summary: If ``0`` or ``0L`` is directly used, the code is not clear and
-type security cannot be ensured. If ``NULL`` is used, the type security
-cannot be ensured. These are all potential risks.
-
-``nullptr`` has many advantages. It literally represents the null
-pointer and makes the code clearer. More to the point, it is no longer
-an integer type.
-
-``nullptr`` is of the ``std::nullptr_t`` type. ``std::nullptr_t`` can be
-implicitly converted into all original pointer types, so that
-``nullptr`` can represent a null pointer that points to any type.
-
-.. code:: cpp
-
- void F(int);
- void F(int*);
- F(nullptr); // Call F(int*).
-
- auto result = Find(id);
- if (result == nullptr) { // Find() returns a pointer.
- // do something
- }
-
-Rule 10.1.4 Use ``using`` instead of ``typedef``.
--------------------------------------------------
-
-For versions earlier than ``C++11``, you can define the alias of the
-type by using ``typedef``. No one wants to repeat code like
-``std::map<uint32_t, std::vector<int>>``.
-
-.. code:: cpp
-
- typedef std::map<uint32_t, std::vector<int>> SomeType;
-
-Using alias for the type is actually encapsulating the type. This
-encapsulation makes the code clearer, and to a large extent avoids the
-bulk modification caused by the type change. For versions supporting C++
-11 features, ``using`` is provided to implement ``alias declarations``:
-
-.. code:: cpp
-
- using SomeType = std::map<uint32_t, std::vector<int>>;
-
-Compare the two formats:
-
-.. code:: cpp
-
- typedef Type Alias; // It cannot be told whether the original Type or Alias is at the front.
- using Alias = Type; // The format confirms to the assignment rule. It is easy to understand and helps reduce errors.
-
-If this is not enough to prove the advantages of ``using``, the alias
-template may be a better example:
-
-.. code:: cpp
-
- //: Only one line of code is need to define an alias for a template.
- template<class T>
- using MyAllocatorVector = std::vector<T, MyAllocator<T>>;
-
- MyAllocatorVector data; // An alias for a template defined with "using".
-
- template<class T>
- class MyClass {
- private:
- MyAllocatorVector data_; // Another.
- };
-
-``typedef`` does not support alias templates and they have to be hacked
-in.
-
-.. code:: cpp
-
- // A template is used for packaging typedef. Therefore, a template class is needed.
- template<class T>
- struct MyAllocatorVector {
- typedef std::vector<T, MyAllocator<T>> type;
- };
-
- MyAllocatorVector::type data; // ::type needs to be added when using typedef to define an alias.
-
- template<class T>
- class MyClass {
- private:
- typename MyAllocatorVector::type data_; // For a template class, typename is also needed in addition to ::type.
- };
-
-Rule 10.1.5 Do not use std::move to operate the const object.
--------------------------------------------------------------
-
-Literally, ``std::move`` means moving an object. The const object cannot
-be modified and cannot be moved. Therefore, using ``std::move`` to
-operate the const object may confuse code readers. Regarding actual
-functions, ``std::move`` converts an object to the rvalue reference
-type. It can convert the const object to the rvalue reference of const.
-Because few types define the move constructor and the move assignment
-operator that use the const rvalue reference as the parameter, the
-actual function of code is often degraded to object copy instead of
-object movement, which brings performance loss.
-
-**Bad example:**
-
-.. code:: cpp
-
- std::string g_string;
- std::vector<std::string> g_stringList;
-
- void func()
- {
- const std::string myString = "String content";
- g_string = std::move(myString); // Bad: myString is not moved. Instead, it is copied.
- const std::string anotherString = "Another string content";
- g_stringList.push_back(std::move(anotherString)); // Bad: anotherString is not moved. Instead, it is copied.
- }
-
-Smart Pointers
-==============
-
-Rule 10.2.1 Use smart pointers instead of a raw pointer to manage resources.
-----------------------------------------------------------------------------
-
-**Reason:** Avoid resource leakage.
-
-**Example:**
-
-.. code:: cpp
-
- void Use(int i)
- {
- auto p = new int {7}; // Bad: Initializing local pointers with new.
- auto q = std::make_unique(9); // Good: Guarantee that memory is released.
- if (i > 0) {
- return; // Return and possible leak.
- }
- delete p; // Too late to salvage.
- }
-
-**Exception:** Raw pointers can be used in scenarios requiring high
-performance and compatibility.
-
-Rule 10.2.2 Use ``unique_ptr`` instead of ``shared_ptr``.
----------------------------------------------------------
-
-**Reasons:**
-#. Using ``shared_ptr`` a lot has an overhead (atomic operations on the ``shared_ptr``\ s reference count have a measurable
-cost).
-#.Shared ownership in some cases (such as circular dependency) may create objects that can never be released.
-#.Shared ownership can be an attractive alternative to careful ownership design but it may obfuscate the design of a system.
-
-Rule 10.2.3 Use ``std::make_unique`` instead of ``new`` to create a ``unique_ptr``.
------------------------------------------------------------------------------------
-
-**Reasons:**
-#. ``make_unique`` provides a simpler creation method.
-#. ``make_unique`` ensures the exception safety of complex expressions.
-
-**Example:**
-
-.. code:: cpp
-
- // Bad: MyClass appears twice, which carries a risk of inconsistency.
- std::unique_ptr<MyClass> ptr(new MyClass(0, 1));
- // Good: MyClass appears once and there is no possibility of inconsistency.
- auto ptr = std::make_unique<MyClass>(0, 1);
-
-Recurrence of types may cause serious problems, and it is difficult to
-find them:
-
-.. code:: cpp
-
- // The code compiles fine, but new and delete usage does not match.
- std::unique_ptr<uint8_t> ptr(new uint8_t[10]);
- std::unique_ptr<uint8_t[]> ptr(new uint8_t);
- // No exception safety: The compiler may calculate parameters in the following order:
- // 1. Allocate the memory of Foo.
- // 2. Construct Foo.
- // 3. Call Bar.
- // 4. Construct unique_ptr<Foo>.
- // If Bar throws an exception, Foo is not destroyed and a memory leak occurs.
- F(unique_ptr<Foo>(new Foo()), Bar());
-
- // Exception safety: Calling of function is not interrupted.
- F(make_unique<Foo>(), Bar());
-
-**Exception:** ``std::make_unique`` does not support user-defined
-``deleter``. In the scenario where the ``deleter`` needs to be
-customized, it is recommended that ``make_unique`` be implemented in the
-customized version’s own namespace. Using ``new`` to create
-``unique_ptr`` with the user-defined ``deleter`` is the last choice.
-
-Rule 10.2.4 Create ``shared_ptr`` by using ``std::make_shared`` instead of ``new``.
------------------------------------------------------------------------------------
-
-**Reason:** In addition to the consistency factor similar to that in
-``std::make_unique`` when using ``std::make_shared``, performance is
-also a factor to consider. ``std::shared_ptr`` manages two entities: \*
-Control block (storing reference count, ``deleter``, etc.) \* Managed
-objects
-
-When ``std::make_shared`` creates ``std::shared_ptr``, it allocates
-sufficient memory for storing control blocks and managed objects on the
-heap at a time. When ``std::shared_ptr<MyClass>(new MyClass)``\ is used
-to create a ``std::shared_ptr``, not only does ``new MyClass`` trigger
-heap allocation, but the constructor function of ``std::shard_ptr``
-triggers a second heap allocation, resulting in extra overhead.
-
-**Exception:** Similar to ``std::make_unique``, ``std::make_shared``
-does not support ``deleter`` customization.
-
-Lambda
-======
-
-Recommendation 10.3.1 Use ``lambda`` to capture local variables or write local functions when normal functions do not work.
----------------------------------------------------------------------------------------------------------------------------
-
-**Reason:** Functions cannot capture local variables or be declared at
-local scope. If you need those things, choose ``lambda`` instead of
-handwritten ``functor``. On the other hand, ``lambda`` and ``functor``
-objects do not support overloading. If overloading is required, use a
-function. If both ``lambda`` and functions work, a function is
-preferred. Use the simplest tool.
-
-**Example:**
-
-.. code:: cpp
-
- // Write a function that accepts only an int or string.
- // -- Overloading is more natural.
- void F(int);
- void F(const string&);
-
- // The local state needs to be captured or appear in the statement or expression range.
- // -- A lambda is more natural.
- vector<Work> v = LotsOfWork();
- for (int taskNum = 0; taskNum < max; ++taskNum) {
- pool.Run([=, &v] {...});
- }
- pool.Join();
-
-Rule 10.3.1 Avoid capturing by reference in lambdas that will not be used locally.
-----------------------------------------------------------------------------------
-**Reason:** Using ``lambdas`` at a “nonlocal†scope includes returning,
-storing on the heap, and passing to another thread. Local pointers and
-references should not outlive their scope. Capturing by reference in
-``lambdas`` indicates storing a reference to a local object. If this
-leads to a reference that exceeds the lifecycle of a local variable,
-capturing by reference should not be used.
-
-**Example:**
-
-.. code:: cpp
-
- // Bad
- void Foo()
- {
- int local = 42;
- // Capture a reference to a local variable.
- // After the function returns results, local no longer exists,
- // Process() call will have undefined behavior.
- threadPool.QueueWork([&]{ Process(local); });
- }
-
- // Good
- void Foo()
- {
- int local = 42;
- // Capture a copy of local.
- // Since a copy of local is made, it will be always available for the call.
- threadPool.QueueWork([=]{ Process(local); });
- }
-
-Recommendation 10.3.2 All variables are explicitly captured if ``this`` is captured.
-------------------------------------------------------------------------------------
-
-**Reason:** The ``[=]`` in the member function seems to indicate
-capturing by value but actually it is capturing data members by
-reference because it captures the invisible ``this`` pointer by value.
-Generally, it is recommended that capturing by reference be avoided. If
-it is necessary to do so, write ``this`` explicitly.
-
-**Example:**
-
-.. code:: cpp
-
- class MyClass {
- public:
- void Foo()
- {
- int i = 0;
-
- auto Lambda = [=]() { Use(i, data_); }; // Bad: It looks like we are copying or capturing by value but member variables are actually captured by reference.
-
- data_ = 42;
- Lambda(); // Call use(42);
- data_ = 43;
- Lambda(); // Call use(43);
-
- auto Lambda2 = [i, this]() { Use(i, data_); }; // Good: the most explicit and least confusing method.
- }
-
- private:
- int data_ = 0;
- };
-
-Recommendation 10.3.3 Avoid default capture modes.
---------------------------------------------------
-
-**Reason:** The lambda expression provides two default capture modes:
-by-reference (&) and by-value (=). By default, the “by-referenceâ€
-capture mode will implicitly capture the reference of all local
-variables, which will easily lead to dangling references. By contrast,
-explicitly writing variables that need to be captured can make it easier
-to check the lifecycle of an object and reduce the possibility of making
-a mistake. By default, the “by-value†capture mode will implicitly
-capture this pointer, and it is difficult to find out which variables
-the lambda function depends on. If a static variable exists, the reader
-mistakenly considers that the lambda has copied a static variable.
-Therefore, it is required to clearly state the variables that lambda
-needs to capture, instead of using the default capture mode.
-
-**Bad example:**
-
-.. code:: cpp
-
- auto func()
- {
- int addend = 5;
- static int baseValue = 3;
-
- return [=]() { // Only addend is actually copied.
- ++baseValue; // The modification will affect the value of the static variable.
- return baseValue + addend;
- };
- }
-
-**Good example:**
-
-.. code:: cpp
-
- auto func()
- {
- int addend = 5;
- static int baseValue = 3;
-
- return [addend, baseValue = baseValue]() mutable { // Uses the C++14 capture initialization to copy a variable.
- ++baseValue; // Modifying the copy of a static variable does not affect the value of the static variable.
- return baseValue + addend;
- };
- }
-
-Reference: Effective Modern C++: Item 31: Avoid default capture modes.
-
-Interfaces
-==========
-
-Recommendation 10.4.1 Use ``T*`` or ``T&`` arguments instead of a smart pointer in scenarios where ownership is not involved.
------------------------------------------------------------------------------------------------------------------------------
-
-**Reasons:** 1. Passing a smart pointer to transfer or share ownership
-should only be used when the ownership mechanism is explicitly required.
-2. Passing a smart pointer (for example, passing the ``this`` smart
-pointer) restricts the use of a function to callers using smart
-pointers. 3. Passing a shared smart pointer adds a runtime performance
-cost.
-
-**Example:**
-
-.. code:: cpp
-
- // Accept any int*.
- void F(int*);
-
- // Accept only integers for which you want to transfer ownership.
- void G(unique_ptr<int>);
-
- // Accept only integers for which you want to share ownership.
- void G(shared_ptr<int>);
-
- // Does not need to change the ownership but requires ownership of the caller.
- void H(const unique_ptr<int>&);
-
- // Accept any int.
- void H(int&);
-
- // Bad
- void F(shared_ptr<Widget>& w)
- {
- // ...
- Use(*w); // When only w is used, lifecycle management is not required.
- // ...
- };
diff --git a/readme/Contributing to the Code.rst b/readme/Contributing to the Code.rst
deleted file mode 100644
index 4818e65..0000000
--- a/readme/Contributing to the Code.rst
+++ /dev/null
@@ -1,23 +0,0 @@
-.. _Contributingcode:
-
-.. include:: ../definitions.rst
-
-Contributing Code
-#################
-
-Start Contributions
-*******************
-Code Style
-==========
-
-Develop, review, and test code following the |main_project_name| coding standards. Make sure code is written in the same style.
-
-* :ref:`C++ Coding Style Guide <C++coding-style>`
-* :ref:`JavaScript Coding Style Guide <javaCode-style>`
-* `Python Coding Style Guide <https://pep8.org/>`_
-
-
-Contribution Workflow
-*********************
-
-For details, see `Contribution Process <https://git.ostc-eu.org/docs/developer-guide/-/blob/master/documentation/source/readme/Contribution%20Process.rst>`_.
diff --git a/readme/JavaScript Coding Style Guide.rst b/readme/JavaScript Coding Style Guide.rst
deleted file mode 100644
index 1dd1c43..0000000
--- a/readme/JavaScript Coding Style Guide.rst
+++ /dev/null
@@ -1,968 +0,0 @@
-.. _javaCode-style:
-
-.. include:: ../definitions.rst
-
-JavaScript Coding Style Guide
-#############################
-
-Goal
-****
-
-Rules are not perfect. Prohibiting features that are useful in specific
-situations can have an impact on code implementation, but we set the
-rules for the benefit of most programmers. If we identify a rule cannot
-be followed in the operations, we should work together to improve the
-rule. You are supposed to have the basic JavaScript language
-capabilities to refer to this guide, instead of learning the JavaScript
-language from it.
-
-General Principles
-******************
-
-The code is required to be **readable, maintainable, secure, reliable,
-testable, efficient, and portable** on the premise that the functions
-are correct.
-
-Convention
-**********
-
-**Rule**: Conventions that must be complied with during programming
-**Recommendation**: Conventions that must be considered during
-programming
-
-It is important to understand why this convention is so stated in both
-“Rules†or “Recommendations†and make efforts to comply.
-
-Exceptions
-**********
-
-If the General Principle is not violated, the rules can be properly
-violated after full consideration and sufficient reasons are provided.
-Exceptions compromise code consistency so please avoid exceptions.
-Exceptions to “Rules†should be rare.
-
-The style consistency principle is preferred in the following
-situations: **When modifying external open-source code and third-party
-code, comply with the existing rules of the open-source code and
-third-party code and keep the style consistent.**
-
-Programming Regulations
-***********************
-
-Naming Regulations
-==================
-
-Rule 1.1 Use correct English spellings to name, no use of pinyin spellings.
----------------------------------------------------------------------------
-
-**Counterexample:**\ ``xingming``,\ ``zhanghao``
-
-**Example:**\ ``username``,\ ``account``
-
-Rule 1.2 Use abbreviations as few as possible, except for common words or professional words. For example, ``context`` can be shortened to ``ctx``, ``request`` can be shortened to ``req``, and ``response`` can be shortened to ``resp``.
--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-
-**Note:** Complete spelling of words can avoid unnecessary
-misunderstanding.
-
-**Exceptions:** The variable name of the cyclic condition can be ``i``
-or ``j`` in the cyclic language.
-
-Rule 1.3 Class name, enumeration name and namespace name should comply the ``upperCamelCase`` style.
-----------------------------------------------------------------------------------------------------
-
-**Example:**
-
-.. code:: javascript
-
- // Class name
- class User {
- constructor(username) {
- this.username = username;
- }
-
- sayHi() {
- console.log(`hi, ${this.username}`);
- }
- }
-
- // Enumeration name
- const UserType = {
- TEACHER: 0,
- STUDENT: 1
- };
-
- // Namespace
- const Base64Utils = {
- encrypt: function(text) {
- // todo encrypt
- },
- decrypt: function(text) {
- // todo decrypt
- }
- };
-
-Rule 1.4 Variable name, method name, and parameter name should comply the ``lowerCamelCase`` style.
----------------------------------------------------------------------------------------------------
-
-**Example:**
-
-.. code:: javascript
-
- let msg = 'Hello world';
-
- function sendMsg(msg) {
- // todo send message
- }
-
- function findUser(userID) {
- // todo find user by user ID
- }
-
-Rule 1.5 The names of static constants and enumeration values must be in upper case, and words are separated by underscores (_).
---------------------------------------------------------------------------------------------------------------------------------
-
-**Example:**
-
-.. code:: javascript
-
- const MAX_USER_SIZE = 10000;
-
- const UserType = {
- TEACHER: 0,
- STUDENT: 1
- };
-
-Recommendation 1.6 Do not use negative Boolean variable names. Local variables or methods of the Boolean type must be prefixed with expressions with the meaning of right or wrong.
------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------
-
-**Counterexample:**
-
-.. code:: javascript
-
- let isNoError = true;
- let isNotFound = false;
- function empty() {}
- function next() {}
-
-**Example:**
-
-.. code:: javascript
-
- let isError = false;
- let isFound = true;
- function isEmpty() {}
- function hasNext() {}
-
-Code Format
-===========
-
-Rule 2.1 Use two spaces to indent, and do not use the ``tab`` character.
-------------------------------------------------------------------------
-
-**Note:** Only spaces are allowed for indentation. Two spaces are
-allowed at a time. Tab characters are not allowed for indentation.
-
-**Example:**
-
-.. code:: javascript
-
- const dataSource = [
- {
- id: 1,
- title: 'Title 1',
- content: 'Content 1'
- },
- {
- id: 2,
- title: 'Title 2',
- content: 'Content 2'
- }
- ];
-
- function render(container, dataSource) {
- if (!container || !dataSource || !dataSource.length) {
- return void 0;
- }
-
- const fragment = document.createDocumentFragment();
- for (let data of dataSource) {
- if (!data || !data.id || !data.title || !data.content) {
- continue;
- }
- const element = document.createElement("div");
- const textNode = document.createTextNode(`${data.title}: ${data.content}`);
- element.appendChild(textNode);
- element.setAttribute("id", data.id);
- fragment.appendChild(element);
- }
- container.appendChild(fragment);
- }
-
-Rule 2.2 The line width cannot exceed 120 characters.
------------------------------------------------------
-
-**Note:** It is recommended that each line should contain no more than
-120 characters. Use a proper method to break the line if the line
-contain more than 120 characters.
-
-**Exception:** If a line of comments contains more than 120 characters
-of commands or URLs, keep it in one line for easy copying, pasting, and
-searching by running the grep command. The preprocessed error
-information is easy to read and understand in one line, even if it
-contains more than 120 characters.
-
-Rule 2.3 The use of braces must comply with the following conventions:
-----------------------------------------------------------------------
-
-1. If the value in the braces is empty, the value can be abbreviated as
- ``{}`` without a newline.
-2. The left braces do not contain a line feed, and the left braces are
- followed by a line feed.
-3. Line feeds before the right brace. If there is ``else`` or ``catch``
- after the brace, line feeds are not required. In other cases, line
- feeds are required.
-
-Rule 2.4 Implementations of conditional and loop statements must be enclosed in braces, even if there is only one statement.
-----------------------------------------------------------------------------------------------------------------------------
-
-**Counterexample:**
-
-.. code:: javascript
-
- if (condition)
- console.log('success');
-
- for(let idx = 0; idx < 5; ++idx)
- console.log(idx);
-
-**Example:**
-
-.. code:: javascript
-
- if (condition) {
- console.log('success');
- }
-
- for(let idx = 0; idx < 5; ++idx) {
- console.log(idx);
- }
-
-Rule 2.5 Condition statements and loop statements cannot be written in one line.
---------------------------------------------------------------------------------
-
-**Counterexample:**
-
-.. code:: javascript
-
- if (condition) { /* todo something */ } else { /* todo other */ }
-
- let idx = 0;
- while(idx < 10) console.log(idx);
-
-**Example:**
-
-.. code:: javascript
-
- if (condition) {
- /* todo something */
- } else {
- /* todo other */
- }
-
- let idx = 0;
- while(idx < 10) {
- console.log(idx);
- }
-
-Rule 2.6 The ``case`` and ``default`` in the ``switch`` statement must be indented by one layer.
-------------------------------------------------------------------------------------------------
-
-**Example:**
-
-.. code:: javascript
-
- switch(condition) {
- case 0:
- doSomething();
- break;
- case 1: { // the braces is not necessary
- doOtherthing();
- break;
- }
- default:
- break;
- }
-
-Rule 2.7 The line feeds of expressions must be consistent, and the operator must be placed at the end of the line.
-------------------------------------------------------------------------------------------------------------------
-
-**Note:** If a long expression does not meet the line width requirement,
-you need to wrap the line in a proper position. Generally, in the late
-phrase of the lower-priority operator or connector, the operator or
-connector should be placed at the end of the line. The operator and
-separator are placed at the end of the line, indicating that there is
-not the end.
-
-**Example:**
-
-.. code:: javascript
-
- // if the condition statement exceeds the line width.
- if (userCount > MAX_USER_COUNT ||
- userCount < MIN_USER_COUNT) {
- doSomething();
- }
-
- const sum =
- number1 +
- number2 +
- number3 +
- number4 +
- number5 +
- number6 +
- number7 +
- number8 +
- number9;
-
-Rule 2.8 Multiple variable definitions and assignment statements cannot be written in one line.
------------------------------------------------------------------------------------------------
-
-**Counterexample:**
-
-.. code:: javascript
-
- let maxCount = 10, isCompleted = false;
-
- let pointX, pointY;
- pointX = 10; pointY = 0;
-
-**Example:**
-
-.. code:: javascript
-
- let maxCount = 10;
- let isCompleted = false;
-
- let pointX = 0;
- let pointY = 0;
-
-Rule 2.9 Spaces should highlight keywords and important information. Avoid unnecessary spaces.
-----------------------------------------------------------------------------------------------
-
-**Note:** Spaces reduce code density and increase code readability. The
-general rules are as follows:
-
-1. Add a spaces after keywords
- ``if``\ ã€\ ``elseif``\ ã€\ ``else``\ ã€\ ``switch``\ ã€\ ``while``\ ã€\ ``for``.
-2. No space is added between the parentheses.
-3. Spaces must be added on both sides of the braces, except for simple
- scenarios such as ``{}``.
-4. No space is added between multiple parentheses.
-5. No space is added after unary operators (``&``, ``*``, ``+``, ``-``,
- ``!``,etc.).
-6. Add a space on the left and right side of binary operators
- ``=``\ ã€\ ``+``\ ã€\ ``-``\ ã€\ ``*``\ ã€\ ``/``\ ã€\ ``%``\ ã€\ ``|``\ ã€\ ``&``\ ã€\ ``||``\ ã€\ ``&&``\ ã€\ ``<``\ ã€\ ``>``\ ã€\ ``<=``\ ã€\ ``>=``\ ã€\ ``==``\ ã€\ ``!=``\ ã€\ ``===``\ ã€\ ``!==``,
- etc.)
-7. Add a space on the left and right side of ternary operator
- （\ ``?:``\ ）.
-8. No space is added between the preceded or post-decrease (``++``,
- ``--``) and variables.
-9. Add a space before a comma (``,``).
-10. Add a space after ``//`` in a single line.
-11. No space is added at the end of the line.
-
-Rule 2.10 Expression statements must end with a semicolon.
-----------------------------------------------------------
-
-**Counterexample:**
-
-.. code:: javascript
-
- let username = 'jack'
- let birthday = '1997-09-01'
-
- console.log(`${username}'s birthday is ${birthday}`)
-
-**Example:**
-
-.. code:: javascript
-
- let username = 'jack';
- let birthday = '1997-09-01';
-
- console.log(`${username}'s birthday is ${birthday}`);
-
-Recommendation 2.11 Use single quotation marks to wrap strings first.
----------------------------------------------------------------------
-
-**Example:**
-
-.. code:: javascript
-
- let message = 'wolrd';
- console.log(message);
-
-Code instructions
-=================
-
-Rule 3.1 When declaring a variable, use the keyword ``var``, ``let``, or ``const`` to prevent the variable from being exposed to the global scope.
---------------------------------------------------------------------------------------------------------------------------------------------------
-
-**Note:** If the keyword ``var``, ``let``, or ``const`` is not used to
-declare a variable, the variable will be exposed to the global scope,
-which may overwrite the variable with the same name in the global scope.
-As a result, the GC cannot effectively reclaim the memory. In addition,
-when a variable contains sensitive information, exposuring to the global
-scope may result in information leakage. \*\* Use ``const`` instead of
-``var`` for all references; Use ``let`` instead of ``var`` if you need a
-variable reference.*\* Because the scope of ``const`` and ``let`` is
-smaller, writing code is easier to control. Const ensures that the
-reference cannot be re-assigned. The pointer referenced by const is
-immutable, and an error will be reported during re-assignment, avoiding
-overwriting.
-
-**Counterexample:**
-
-.. code:: javascript
-
- function open() {
- url = 'http://127.0.0.1:8080'; //url will be exposed to the global scope
- //todo something
- }
- open();
- console.log(url); //url can be accessed, output: http://127.0.0.1:8080
-
-**Example:**
-
-.. code:: javascript
-
- // ES5.1 Using var to declare variables
- function open() {
- var url = 'http://127.0.0.1:8080';
- // todo something
- }
- open();
- console.log(url); //Report: Uncaught ReferenceError: url is not defined
-
-.. code:: javascript
-
- // In ES6, the let and const keywords are preferred to declare variables.
- function open() {
- const url = 'http://127.0.0.1:8080';
- //todo something
- }
- open();
- console.log(url); //Report: Uncaught ReferenceError: url is not defined
-
-Rule 3.2 Function expressions must be used to declare functions in function blocks.
------------------------------------------------------------------------------------
-
-**Note:** Although many JS engines support in-block declaration
-functions, they do not belong to the ECMAScript specification. The poor
-implementation of browsers is incompatible with each other, and some are
-contrary to the future ECMAScript draft. In addition, ECMAScript5 does
-not support block scopes. All control flows are not independent scopes.
-Variables or functions declared in the control flows are in the scope of
-their parent functions or scripts. As a result, the declaration of
-functions or variables in blocks may be overwritten. If you do need to
-define a function in a block, you should initialize it using a function
-expression.
-
-**Counterexample:**
-
-.. code:: javascript
-
- function bar(name) {
- if (name === "hotel") {
- // 1. Define a foo function. The function scope is not the 'if' code block but the 'bar' function scope.
- function foo() {
- console.log("hotel foo A");
- }
- } else {
- // 2. Define the 'foo' function again to overwrite the 'foo' function definition under the 'if' condition branch.
- function foo() {
- console.log("hotel foo 2");
- }
- }
- foo && foo();
- }
- bar("hotel"); // output is shown as"hotel foo 2"
-
-**Example:**
-
-.. code:: javascript
-
- function bar(name) {
- var foo;
- if (name == "hotel") {
- foo = function () {
- console.log("hotel foo 1");
- };
- } else {
- foo = function () {
- console.log("hotel foo 2");
- }
- }
- foo && foo();
- }
- bar("hotel"); // Correct output"hotel foo 1"
-
-Rule 3.3 Encapsulation of Basic Types is prohibited
----------------------------------------------------
-
-**Note:** JavaScript has five basic data types: Undefined, Null,
-Boolean, Number, and String. The value of the base data type is
-unchangeable. The basic data type object used in JavaScript is only a
-value. It does not contain the methods and attributes of the object
-encapsulated by the object. When the attributes and methods are not
-required, the encapsulation type of the object does not need to be used.
-
-**Counterexample:**
-
-.. code:: javascript
-
- var isShow = new Boolean(false);
- if (isShow) {
- alert('hi'); //It is executed, and the following information is displayed: hi
- }
-
-**Example:**
-
-.. code:: javascript
-
- var isShow = false;
- if (isShow) {
- alert('hi');
- }
-
-Rule 3.4 The use of ``with`` is prohibited
-------------------------------------------
-
-**Note:** Using ‘with’ makes your code semantically unclear, because
-objects of ‘with’ may conflict with local variables, changing the
-original meaning of the program.
-
-**Counterexample:**
-
-.. code:: javascript
-
- var foo = { x: 5 };
- with(foo) {
- var x = 3;
- console.log(x); //Output: 5
- }
-
-Rule 3.5 ``this`` can only be used in object constructors, methods, and closures.
----------------------------------------------------------------------------------
-
-**Note:** In JavaScript, the “this†pointer represents the owner of the
-object that executes the current code. This has special semantics:
-
-- Global objects (in most cases)
-- Scope of the caller (when eval is used)
-- Nodes in the DOM tree (when adding event handling functions)
-- Newly created object (using a constructor)
-- Other objects (if the function is called() or apply())
-
-.. code:: javascript
-
- var User = function(username) {
- this.username = username;
- };
- var user = new User('John');
- console.log(user.username); // Output: John
-
- var ClickCounter = {
- value: 0,
- click: function() {
- ++this.value;
- },
- getValue() {
- return this.value;
- }
- };
- console.log(Counter.getValue()); //Output: 0
- Counter.click();
- console.log(Counter.getValue()); //Output: 1
-
-Rule 3.6 Do not use conditional comments in IE.
------------------------------------------------
-
-**Note:** Conditional compilation can be activated using the ``\@cc_on``
-statement or the ``\@if`` or ``\@set`` statement in IE. Although
-comments can be made to be compatible with browsers other than IE, they
-hinder the execution of automation tools because they change the
-JavaScript syntax tree at run time.
-
-**Counterexample:**
-
-.. code:: javascript
-
- var f = function () {
- /*@cc_on @*/
- /*@if (@_jscript_version >= 4)
- alert("JavaScript version 4 or better");
- @else @*/
- alert("Conditional compilation not supported by this scripting engine.");
- /*@end @*/
- };
-
-Rule 3.7 Prototypes of built-in objects cannot be modified.
------------------------------------------------------------
-
-**Note:** As a set of public interfaces, built-in objects have
-conventional behaviors. Modifying the prototype may damage the interface
-semantics or cause abnormalities during debugging.
-
-**Counterexample:**
-
-.. code:: javascript
-
- Array.prototype.indexOf = function () { return -1 }
- var arr = [1, 1, 1, 1, 1, 2, 1, 1, 1];
- console.log(aar.indexOf(2)); // Output:-1
-
-Rule 3.8 Do not directly use the built-in attribute of ``Object.prototype``.
-----------------------------------------------------------------------------
-
-**Note:** ECMAScript 5.1 adds ``Object.create``, which creates a new
-object and uses an existing object to provide the proto of the newly
-created object. ``Object.create(null)`` is a common pattern for creating
-objects used as maps. Unexpected behavior or vulnerability may occur
-when the object has an attribute with the same name as
-``Object.prototype``. For example, it is not safe for a web server to
-parse JSON input from a client and use ``hasOwnProperty`` to directly
-invoke the generated object, because a malicious client may send a
-similar JSON value ``' {"hasOwnProperty": 1} '`` and cause the server to
-crash.
-
-**Counterexample:**
-
-.. code:: javascript
-
- var hasBarProperty = foo.hasOwnProperty("bar");
- var isPrototypeOfBar = foo.isPrototypeOf(bar);
- var barIsEnumerable = foo.propertyIsEnumerable("bar");
-
-**Example:**
-
-.. code:: javascript
-
- var hasBarProperty = Object.prototype.hasOwnProperty.call(foo, "bar");
- var isPrototypeOfBar = Object.prototype.isPrototypeOf.call(foo, bar);
- var barIsEnumerable = {}.propertyIsEnumerable.call(foo, "bar");
-
-Rule 3.9 Use the ``Object.getPrototypeOf`` function instead of ``_proto_``
---------------------------------------------------------------------------
-
-**Note:** ES5 introduces the ``Object.getPrototypeOf`` function as the
-standard API for obtaining object prototypes, but a large number of
-JavaScript engines have long used a special
-``proto' attribute to achieve the same purpose. However,``\ proto\` is
-essentially an internal attribute rather than a formal external API.
-Currently, this attribute must be deployed in browsers, but not in other
-running environments. Therefore, this attribute is not fully compatible.
-For example, objects with null prototypes are handled differently in
-different environments.
-
-.. code:: javascript
-
- var empty = Object.create(null);
- "_proto_" in empty; //Some environments false is returned, some environments true is returned.
-
-Therefore, use ``Object.getPrototypeOf()`` instead of using the proto
-attribute in terms of semantics and compatibility. The
-\`Object.getPrototypeOf’ function is valid in any environment and is a
-more standard and portable method for extracting object prototypes.
-
-Rule 3.10 Do not create functions with function constructors.
--------------------------------------------------------------
-
-**Note:** There are three methods for defining a function: function
-declaration, function constructor, and function expression. Regardless
-of in which method you define a function, they are instances of the
-Function object and inherit all default or custom methods and properties
-of the Function object. The method of creating a function using a
-function constructor is similar to the character string ``eval()``. Any
-character string can be used as the function body, which may cause
-security vulnerabilities.
-
-**Counterexample:**
-
-.. code:: javascript
-
- var func = new Function('a', 'b', 'return a + b');
- var func2 = new Function('alert("Hello")');
-
-**Example:**
-
-.. code:: javascript
-
- function func(a, b) {
- return a + b;
- }
-
- var func2 = function(a, b) {
- return a + b;
- }
-
-Suggestion 3.11 When using the prototype \`prototype’ to implement inheritance, try to use the existing stable library methods instead of self-implementing them.
------------------------------------------------------------------------------------------------------------------------------------------------------------------
-
-**Note:** The multi-level prototype structure refers to the inheritance
-relationship in JavaScript. When you define a class D and use class B as
-its prototype, you get a multilevel prototype structure. These prototype
-structures can get complicated. Using existing stable library methods
-such as ``goog.inherits()`` of the Closure library or other similar
-functions can avoid unnecessary coding errors.
-
-Suggestion 3.12 When defining a class, you should define the method under the prototype and the attributes within the constructor.
-----------------------------------------------------------------------------------------------------------------------------------
-
-**Note:** There are multiple methods in JavaScript to add methods or
-members to constructors. However, using a prototype to define methods
-can reduce memory usage and improve running efficiency.
-
-**Counterexample:**
-
-.. code:: javascript
-
- function Animals() {
- this.walk = function() {}; // This causes a walk method to be created on each instance.
- }
-
-**Example:**
-
-.. code:: javascript
-
- function Animals() {}
-
- Animals.prototype.walk = function() {};
-
-Suggestion 3.13 When using closures, avoid cyclic reference, which may cause memory leakage.
---------------------------------------------------------------------------------------------
-
-**Note:** JavaScript is a garbage collection language in which the
-memory of an object is allocated to the object based on its creation and
-is reclaimed by the browser when there is no reference to the object.
-JavaScript’s garbage collection mechanism is fine on its own, but
-browsers are somewhat different in the way they allocate and recover
-memory for DOM objects. Both IE and Firefox use reference counting to
-process memory for DOM objects. In the reference counting system, each
-referenced object keeps a count to see how many objects are referencing
-it. If the count is zero, the object is destroyed and the memory it
-occupies is returned to the heap. While this solution is generally
-effective, there are some blind spots in circular references. When two
-objects refer to each other, they form a circular reference, where the
-reference counting values of the objects are assigned to 1. In pure
-garbage collection systems, circular references are not a problem: if
-one of the two objects involved is referenced by any other object, both
-objects will be garbage collected. In a reference counting system,
-neither of these objects can be destroyed because reference counting can
-never be 0. In a hybrid system that uses both garbage collection and
-reference counting, a leak occurs because the system does not correctly
-recognize circular references. In this case, neither the DOM object nor
-the JavaScript object can be destroyed. Circular references are easy to
-create. Circular references are particularly prominent in closures, one
-of JavaScript’s most convenient programming structures. Closures hold
-references to their external scopes (including local variables,
-parameters, and methods). When the closure itself is held by scope
-members (usually DOM objects), circular references are formed, which
-further leads to memory leaks.
-
-**Counterexample:**
-
-.. code:: javascript
-
- function setClickListener(element, a, b) {
- element.onclick = function() {
- // Use a and b here
- };
- };
-
-In the above code, the closure retains references to elements, a, and b
-even if element is not used. Because the element also retains the
-reference to the closure, a circular reference is generated and cannot
-be recycled by the GC.
-
-**Example:**
-
-.. code:: javascript
-
- function setClickListener(element, a, b) {
- element.onclick = createHandler(a, b);
- }
-
- function createHandler(a, b) {
- // By adding another function to avoid the closure itself, you can organize memory leaks.
- return function() {
- // Use a and b here
- }
- }
-
-Suggestion 3.14 Watch out for JavaScript floating point numbers.
-----------------------------------------------------------------
-
-**Note:** JavaScript has a single numeric type: ``IEEE 754``
-double-precision floating point number. Having a single numeric type is
-one of the best features of JavaScript. Multiple number types can be a
-source of complexity, confusion and error. However, one of the biggest
-drawbacks of the binary floating-point type is that it does not
-accurately represent the fractional part, causing unexpected precision
-problems, as shown in the following examples.
-
-Sample Code1:
-
-.. code:: javascript
-
- console.log(0.1 + 0.2 === 0.3); // Output: false. Therefore, do not use == or === to compare floating-point numbers.
-
-Sample Code2:
-
-.. code:: javascript
-
- var sum1 = (0.1 + 0.2) + 0.3;
- console.log(sum1); // Output: 0.6000000000000001
-
- var sum2 = 0.1 + (0.2 + 0.3);
- console.log(sum2); // Output: 0.6. Therefore, for binary floating-point numbers, (a + b) + c cannot be guaranteed to produce the same result as a + (b + c).
-
-The effective solutions are as follows:
-
-1. Use integers as much as possible because integers do not need to be
- rounded.
-
-2. The native JavaScript method
- ``Number.prototype.toFixed(digits)``,\ ``digist`` is used to indicate
- the number of digits after the decimal point. The exponential method
- is not used. If necessary, the number is rounded off. This method is
- used to reduce the precision of the calculation result before
- determining the floating-point number calculation result. The sample
- code is as follows:
-
- .. code:: javascript
-
- parseFloat(0.1 + 0.2).toFixed(1); //0.3
-
-3. A very small constant ``Number.EPSILON =.220446049250313e-16`` is
- added to ES6, which is about 0.00000000000000022204.
- ``Number.EPSILON`` is used to determine the calculation error of
- floating-point numbers. If the calculation error of floating-point
- numbers is less than or equal to the value of ``Number.EPSILON``,
- such an error is acceptable. The sample code is as follows:
-
- .. code:: javascript
-
- function isNumberEquals(one, other) {
- return Math.abs(one - other) < Number.EPSILON;
- }
- var one = 0.1 + 0.2;
- var other = 0.3;
- console.log(isNumberEquals(one, other)); // Output: true
-
-4. Use some class library methods that support precise calculation, such
- as ``math.js``.
-
-.. code:: html
-
- <!DOCTYPE html>
- <html>
- <head>
- <script src="https://cdnjs.cloudflare.com/ajax/libs/mathjs/5.0.0/math.js"></script>
- <script type="text/javascript">
- function fn_click() {
- math.config({
- number: "BigNumber",
- });
- var result = math.add(math.bignumber(0.1), math.bignumber(0.2));
- alert(result);
- }
- </script>
- </head>
- <body>
- <input type="button" value="mathjs(0.1+0.2)" onclick="fn_click();" />
- </body>
- </html>
-
-Suggestion 3.15 Do not use the array constructor with variable arguments.
--------------------------------------------------------------------------
-
-**Note:** The method of constructor ``new Array`` is not recommended to
-construct a new array. If the constructor has only one parameter,
-exceptions may occur. In addition, the global definition of the array
-may be modified. Therefore, it is recommended to use the array literal
-notation, that is, ``[]`` notation, to create an array.
-
-**Counterexample:**
-
-.. code:: javascript
-
- const arr1 = new Array(x1, x2, x3);
- const arr2 = new Array(x1, x2);
- const arr3 = new Array(x1);
- const arr4 = new Array();
-
-Except for the third case, all other functions can work properly. If
-``x1`` is an integer, ``arr3`` is an array whose length is ``x1`` and
-values are ``undefined``. If ``x1`` is any other number, an exception is
-thrown, and if it is anything else, it is an array of cells.
-
-**Example:**
-
-.. code:: javascript
-
- const arr1 = [x1, x2, x3];
- const arr2 = [x1, x2];
- const arr3 = [x1];
- const arr4 = [];
-
-This way, you’ll save a lot of trouble.
-
-Similarly, use ``{}`` instead of ``new Object()`` to create objects.
-
-Rule 3.16 String templates are preferred over string links when constructing strings.
--------------------------------------------------------------------------------------
-
-**Note:** The template character strings are more concise and readable.
-
-**Counterexample:**
-
-.. code:: javascript
-
- function sayHi(name) {
- console.log('hi, ' + name);
- }
-
-**Example:**
-
-.. code:: javascript
-
- function sayHi(name) {
- console.log(`hi, ${name}`);
- }
-
-Rule 3.17 Use ``for...of`` for array traversal and ``for...in`` for object traversal.
--------------------------------------------------------------------------------------
-
-**Counterexample:**
-
-.. code:: javascript
-
- let numbers = [1, 2, 3, 4];
- let sum = 0;
- for (let number in numbers) {
- sum += number;
- }
- // sum === 00123;
-
-**Example:**
-
-.. code:: javascript
-
- let numbers = [1, 2, 3, 4];
- let sum = 0;
- for (let number of numbers) {
- sum += number;
- }
- // sum === 10
diff --git a/readme/README.rst b/readme/README.rst
index 62699a1..218f594 100644
--- a/readme/README.rst
+++ b/readme/README.rst
@@ -9,9 +9,6 @@ Contributing Documents
Code of Conduct
Communication in Community
Contribution Process
- Contributing to the Code
- C++ Coding Style Guide
- JavaScript Coding Style Guide
Contributing to the Documentation
reStructuredText Basics
FAQs
--
GitLab