edk II C Coding Standard: Insert Directory Names section

changab · changab · commit bda6c0228d33 · 2022-10-26T13:14:18.000+08:00
Insert 4.2 Directory names as the placeholder and update markdown file names and content of follow up sections. PR: https://github.com/tianocore-docs/edk2-CCodingStandardsSpecification/pull/2/files Signed-off-by: Abner Chang <abner.chang@amd.com> Cc: Ray Ni <ray.ni@intel.com> Cc: Michael D Kinney <michael.d.kinney@intel.com> Cc: Sunil V L <sunilvl@ventanamicro.com> Cc: Abdul Lateef Attar <abdattar@amd.com> Cc: Leif Lindholm <quic_llindhol@quicinc.com> Reviewed-by: Ray Ni <Ray.ni@intel.com> Reviewed-by: Abdul Lateef Attar <abdattar@amd.com>
diff --git a/4_naming_conventions/42_directory_names.md b/4_naming_conventions/42_directory_names.md
@@ -0,0 +1,30 @@
+<!--- @file
+  4.2 Directory Names
+
+  Copyright (C) 2022 Advanced Micro Devices, Inc. All rights reserved.<BR>
+
+  Redistribution and use in source (original document form) and 'compiled'
+  forms (converted to PDF, epub, HTML and other formats) with or without
+  modification, are permitted provided that the following conditions are met:
+
+  1) Redistributions of source code (original document form) must retain the
+     above copyright notice, this list of conditions and the following
+     disclaimer as the first lines of this file unmodified.
+
+  2) Redistributions in compiled form (transformed to other DTDs, converted to
+     PDF, epub, HTML and other formats) must reproduce the above copyright
+     notice, this list of conditions and the following disclaimer in the
+     documentation and/or other materials provided with the distribution.
+
+  THIS DOCUMENTATION IS PROVIDED BY TIANOCORE PROJECT "AS IS" AND ANY EXPRESS OR
+  IMPLIED WARRANTIES, INCLUDING, BUT NOT LIMITED TO, THE IMPLIED WARRANTIES OF
+  MERCHANTABILITY AND FITNESS FOR A PARTICULAR PURPOSE ARE DISCLAIMED. IN NO
+  EVENT SHALL TIANOCORE PROJECT  BE LIABLE FOR ANY DIRECT, INDIRECT, INCIDENTAL,
+  SPECIAL, EXEMPLARY, OR CONSEQUENTIAL DAMAGES (INCLUDING, BUT NOT LIMITED TO,
+  PROCUREMENT OF SUBSTITUTE GOODS OR SERVICES; LOSS OF USE, DATA, OR PROFITS;
+  OR BUSINESS INTERRUPTION) HOWEVER CAUSED AND ON ANY THEORY OF LIABILITY,
+  WHETHER IN CONTRACT, STRICT LIABILITY, OR TORT (INCLUDING NEGLIGENCE OR
+  OTHERWISE) ARISING IN ANY WAY OUT OF THE USE OF THIS DOCUMENTATION, EVEN IF
+  ADVISED OF THE POSSIBILITY OF SUCH DAMAGE.
+
+-->
diff --git a/4_naming_conventions/43_file_names.md b/4_naming_conventions/43_file_names.md
@@ -1,5 +1,5 @@
 <!--- @file
-  4.2 File Names
+  4.3 File Names
 
   Copyright (c) 2006-2017, Intel Corporation. All rights reserved.<BR>
 
@@ -29,25 +29,25 @@
 
 -->
 
-## 4.2 File Names
+## 4.3 File Names
 
-### 4.2.1 There is no limit to file name lengths.
+### 4.3.1 There is no limit to file name lengths.
 
 Do not assume that file names must be 8.3 compatible. Be reasonable though. Let
 the file names be as long as necessary, but no longer. Some operating systems
 limit file names to 32 characters.
 
-### 4.2.2 Spaces in file and directory names are NOT permitted.
+### 4.3.2 Spaces in file and directory names are NOT permitted.
 
 Allowing spaces would cause problems with certain versions of existing industry
 tools and does not provide additional clarity.
 
-### 4.2.3 Never start file names with numbers.
+### 4.3.3 Never start file names with numbers.
 
 Most source control systems will not be able to handle file names that start
 with numbers.
 
-### 4.2.4 Non-standard characters shall not occur in file names.
+### 4.3.4 Non-standard characters shall not occur in file names.
 
 All file names within an EDK II source tree must comply with the following
 regular expression:
diff --git a/4_naming_conventions/44_identifiers.md b/4_naming_conventions/44_identifiers.md
@@ -1,5 +1,5 @@
 <!--- @file
-  4.3 Identifiers
+  4.4 Identifiers
 
   Copyright (c) 2006-2017, Intel Corporation. All rights reserved.<BR>
 
@@ -29,9 +29,9 @@
 
 -->
 
-## 4.3 Identifiers
+## 4.4 Identifiers
 
-### 4.3.1 Identifiers shall not rely on the significance of more than 31 characters.
+### 4.4.1 Identifiers shall not rely on the significance of more than 31 characters.
 
 Identifiers (variable names, labels, structure tags, derived macro names, etc.)
 may be an arbitrary length. The ISO standard only guarantees that language
@@ -42,17 +42,17 @@ has been confirmed that 31 character / case significance is supported by EDK II
 supported tool chains, there is no requirement to ensure uniqueness of
 externals within the first 6 characters.
 
-### 4.3.2 Always make identifier names that are visually distinguishable.
+### 4.4.2 Always make identifier names that are visually distinguishable.
 
 While not as big an issue as it has been in the past, when choosing labels
 ensure that the label is unlikely to be confused with other labels used in the
 file. Ensure that long label names vary by more than one or two characters.
 Ensure that labels don't vary between zero and oh (0 and O), one and ell (1 and
 l). Some also consider 2 and Z, and 5 and S to be similar.
 
-### 4.3.3 Hungarian Prefixes
+### 4.4.3 Hungarian Prefixes
 
-#### 4.3.3.1 Use of Hungarian notation is not allowed
+#### 4.4.3.1 Use of Hungarian notation is not allowed
 
 This set of detailed guidelines for naming variables and routines is a
 convention widely used with the C programming language, especially in
@@ -68,7 +68,7 @@ Global data and module data shall be prefixed with 'g' or 'm', respectively.
 Pointer variables may optionally be prefixed with 'p'. These are the only
 exceptions to the prohibition against Hungarian notation.
 
-#### 4.3.3.2 Any variable with file scope, or better, shall be prefixed by an 'm' or 'g'
+#### 4.4.3.2 Any variable with file scope, or better, shall be prefixed by an 'm' or 'g'
 
 There are no exceptions to this rule. The '`m`' prefix identifies a variable
 with module scope, while a '`g`' prefix identifies a global variable.
@@ -78,13 +78,13 @@ gThisIsAGlobalVariableName
 mThisIsAModuleVariableName
 ```
 
-#### 4.3.3.3 Pointer variables may optionally be prefixed with a 'p'
+#### 4.4.3.3 Pointer variables may optionally be prefixed with a 'p'
 
 Time has shown that pass-by-value vs. pass-by-reference errors are
 significantly reduced with only the introduction of a '`p`' prefix for pointer
 variables.
 
-#### 4.3.3.4 Reasons use of Hungarian prefixes not allowed
+#### 4.4.3.4 Reasons use of Hungarian prefixes not allowed
 
 The abstraction of abstract data types is ignored. Instead, base types based on
 programminglanguage integers or long integers are abstracted. Thus, the names
@@ -100,21 +100,21 @@ Studies have shown that Hungarian notation tends to encourage lazy variable
 names. It's common to focus on the Hungarian prefix without putting effort into
 a descriptive name.
 
-### 4.3.4 Function and Data Names
+### 4.4.4 Function and Data Names
 
-#### 4.3.4.1 Identifiers shall contain mixed upper- and lower-case text.
+#### 4.4.4.1 Identifiers shall contain mixed upper- and lower-case text.
 
 Use of all upper- or all lower-case is very difficult to read because compound
 words cannot be clearly separated.
 
-#### 4.3.4.2 The names of newly created global entities (such as structures, macros, and defines) shall not use an `EFI_` prefix.
+#### 4.4.4.2 The names of newly created global entities (such as structures, macros, and defines) shall not use an `EFI_` prefix.
 
 From now on, the use of `DXE_` and `PEI_` prefixes shall be reserved for DXE and
 PEI drivers, respectively. If a structure happens to apply equally to PEI and
 DXE, it should use the prefix `DXE_`. If a structure is local to a particular
 module only, no special prefix is required.
 
-#### 4.3.4.3 Acronyms are not capitalized in Function and Data Names.
+#### 4.4.4.3 Acronyms are not capitalized in Function and Data Names.
 
 When all letters in an acronym are capitalized, it makes the prior and
 subsequent words visually difficult to distinguish.
@@ -123,14 +123,14 @@ subsequent words visually difficult to distinguish.
 ThisIsAnExampleOfWhatToDoForPci
 ```
 
-#### 4.3.4.4 Never use C keywords or the names of symbols declared in the standard header files as internal symbols.
+#### 4.4.4.4 Never use C keywords or the names of symbols declared in the standard header files as internal symbols.
 
 When you need to use the name of an existing library function for a
 user-defined function, each use of the user-defined function must be paired
 with a corresponding comment. The ISO standard does not, however, guarantee
 that the user-defined function will take priority over the library function.
 
-##### 4.3.4.4.1 List of the C-reserved keywords.
+##### 4.4.4.4.1 List of the C-reserved keywords.
 
 In principle, the ISO standard, reserves all names beginning with underscore +
 capital letter, or with underscore + underscore. External symbols names shall
@@ -162,23 +162,23 @@ not begin with an underscore.
 In addition to those listed, the identifiers asm and fortran are common
 language extensions and should also be treated as reserved.
 
-### 4.3.5 Type and Macro Names
+### 4.4.5 Type and Macro Names
 
-#### 4.3.5.1 Use all capital letters for both #define and typedef declarations.
+#### 4.4.5.1 Use all capital letters for both #define and typedef declarations.
 
 This clearly differentiates static declarations from dynamic data types.
 
-#### 4.3.5.2 Each word of a concept shall be separated by an underscore character.
+#### 4.4.5.2 Each word of a concept shall be separated by an underscore character.
 
 The underscore effectively separates the words, making names more readable.
 
-#### 4.3.5.3 The use of the "_t" suffix, designating a type, is not allowed.
+#### 4.4.5.3 The use of the "_t" suffix, designating a type, is not allowed.
 
 ```
 typedef UINT32 THIS_IS_AN_EXAMPLE_OF_WHAT_TO_DO_FOR_PCI;
 ```
 
-#### 4.3.5.4 The names of guard macros shall end with an underscore character.
+#### 4.4.5.4 The names of guard macros shall end with an underscore character.
 
 The guard macro, used in the `#ifndef` at the start of an include file, uses a
 postfix underscore character '`_`', in its name in order to prevent collision
@@ -200,7 +200,7 @@ be required if the header files are mutually exclusive.
 #endif /* FILE_NAME_H_ */
 ```
 
-#### 4.3.5.5 The #else and #endif clauses of conditional compilation blocks shall be commented to identify their context.
+#### 4.4.5.5 The #else and #endif clauses of conditional compilation blocks shall be commented to identify their context.
 
 If a conditional compilation construct spans more than seven lines, a comment
 shall be added to the construct's `#else` and `#endif` clauses identifying the
diff --git a/4_naming_conventions/45_global_&_module_variables.md b/4_naming_conventions/45_global_&_module_variables.md
@@ -1,5 +1,5 @@
 <!--- @file
-  4.4 Global & Module Variables
+  4.5 Global & Module Variables
 
   Copyright (c) 2006-2017, Intel Corporation. All rights reserved.<BR>
 
@@ -29,7 +29,7 @@
 
 -->
 
-## 4.4 Global & Module Variables
+## 4.5 Global & Module Variables
 
 There is often confusion about what constitutes module variables versus global
 variables. Technically, both global and module variables are defined at file
@@ -45,9 +45,9 @@ small number of routines. On the other hand, a global variable is accessed
 throughout the firmware and as the firmware evolves more code will tend to
 access the data resulting in a large number of uses to track down.
 
-### 4.4.1 Recommendations for Global and Module Variables
+### 4.5.1 Recommendations for Global and Module Variables
 
-#### 4.4.1.1 The use of global and module data is strongly discouraged.
+#### 4.5.1.1 The use of global and module data is strongly discouraged.
 
 Global variables are appropriate for GUID, protocol, PPI definitions and other
 immutable objects. Attempting to create global variables can cause many
@@ -59,7 +59,7 @@ programming issues. A module is defined to be a set of data and routines that
 act on that data. Thus, in EFI a protocol could be thought of as a module. A
 complicated protocol may be built out of several smaller modules.
 
-#### 4.4.1.2 Use locking to protect access to global and module variables.
+#### 4.5.1.2 Use locking to protect access to global and module variables.
 
 This protection is strongly encouraged and especially useful for data that is
 accessed at various task priority levels.
diff --git a/4_naming_conventions/46_name_space_rules.md b/4_naming_conventions/46_name_space_rules.md
@@ -1,5 +1,5 @@
 <!--- @file
-  4.5 Name Space Rules
+  4.6 Name Space Rules
 
   Copyright (c) 2006-2017, Intel Corporation. All rights reserved.<BR>
 
@@ -29,7 +29,7 @@
 
 -->
 
-## 4.5 Name Space Rules
+## 4.6 Name Space Rules
 
 ISO C defines several name spaces (see ISO/IEC 9899:1994 6.1.2.3). The same
 name could be used in a separate name space for a completely different item.
@@ -46,7 +46,7 @@ Name spaces are defined as:
 apply to scope. Scope is described in "Scoping Rules".
 **********
 
-### 4.5.1 Names shall be used consistently within the same type.
+### 4.6.1 Names shall be used consistently within the same type.
 
 For example, structure tags may only be reused as structure types, and union
 tags may be reused only for union types.
@@ -62,7 +62,7 @@ typedef struct MyStruct {
 Because of the similarity of `MyStruct` to `MY_STRUCT`, they may only be used
 to refer to the same structure type.
 
-### 4.5.2 No identifier in one name space may be reused as an identifier in another name space
+### 4.6.2 No identifier in one name space may be reused as an identifier in another name space
 
 Exceptions are structure member and union member names.
 
@@ -85,10 +85,10 @@ typedef struct {
 } BAD_STRUCT;
 ```
 
-### 4.5.3 A typedef name shall be a unique identifier.
+### 4.6.3 A typedef name shall be a unique identifier.
 
 The name that appears at the end of a typedef (`STRUCT_ONE` and `STRUCT_TWO` in
-the example in Section 4.5.2) is known as a _typedef name_. Because of ambiguity
+the example in Section 4.6.2) is known as a _typedef name_. Because of ambiguity
 in the C specifications, and to avoid confusion, and once a typedef name is used
 in a structure declaration, it may not be declared elsewhere
 
@@ -97,10 +97,10 @@ in a structure declaration, it may not be declared elsewhere
 number of files is not a violation of this rule.
 **********
 
-### 4.5.4 A tag name shall be unique.
+### 4.6.4 A tag name shall be unique.
 
 The name after the `struct` in structure definitions (`StructOne` and
-`StructTwo` in the example in 4.5.2) is known as a _structure tag_ or simply a
+`StructTwo` in the example in 4.6.2) is known as a _structure tag_ or simply a
 _tag_. To avoid confusion, once a tag is used for declaring a structure it
 shall not be declared elsewhere.
 
@@ -109,7 +109,7 @@ shall not be declared elsewhere.
 violation of this rule.
 **********
 
-### 4.5.5 Prefix module-scope identifiers for cleaner namespaces.
+### 4.6.5 Prefix module-scope identifiers for cleaner namespaces.
 
 The use of prefixes is not an absolute requirement, but has been shown as a
 successful method of avoiding namespace pollution and makes it easier to meet
diff --git a/README.md b/README.md
@@ -114,3 +114,4 @@ Copyright (c) 2006-2017, Intel Corporation. All rights reserved.
 |          | [#425](https://bugzilla.tianocore.org/show_bug.cgi?id=425) [CCS] clarify line breaking and indentation requirements for multi-line function calls |            |
 |          | [#1656](https://bugzilla.tianocore.org/show_bug.cgi?id=1656) Update all Wiki pages for the BSD+Patent license change with SPDX identifiers        |            |
 |          | [#607](https://bugzilla.tianocore.org/show_bug.cgi?id=607) Document code comment requirements for spurious variable assignments                   |            |
+| 2.3      | Add 4.2 Directory names section and update File names section for the guidelines of module directory and file naming|September 2022||
diff --git a/SUMMARY.md b/SUMMARY.md
@@ -1,7 +1,8 @@
 <!--- @file
   Summary
 
-  Copyright (c) 2006-2017, Intel Corporation. All rights reserved.<BR>
+  Copyright (c) 2006-2022, Intel Corporation. All rights reserved.<BR>
+  Copyright (C) 2022 Advanced Micro Devices, Inc. All rights reserved.<BR>
 
   Redistribution and use in source (original document form) and 'compiled'
   forms (converted to PDF, epub, HTML and other formats) with or without
@@ -49,10 +50,11 @@
   * [3.4 Documentation](3_quick_reference.md#34-documentation)
 * [4 Naming Conventions](4_naming_conventions/README.md#4-naming-conventions)
   * [4.1 General Naming Rules](4_naming_conventions/README.md#41-general-naming-rules)
-  * [4.2 File Names](4_naming_conventions/42_file_names.md#42-file-names)
-  * [4.3 Identifiers](4_naming_conventions/43_identifiers.md#43-identifiers)
-  * [4.4 Global & Module Variables](4_naming_conventions/44_global_&_module_variables.md#44-global--module-variables)
-  * [4.5 Name Space Rules](4_naming_conventions/45_name_space_rules.md#45-name-space-rules)
+  * [4.2 Directory Names](4_naming_conventions/42_file_names.md#42-directory-names)  
+  * [4.3 File Names](4_naming_conventions/43_file_names.md#43-file-names)
+  * [4.4 Identifiers](4_naming_conventions/44_identifiers.md#44-identifiers)
+  * [4.5 Global & Module Variables](4_naming_conventions/45_global_&_module_variables.md#45-global--module-variables)
+  * [4.6 Name Space Rules](4_naming_conventions/46_name_space_rules.md#46-name-space-rules)
 * [5 Source Files](5_source_files/README.md#5-source-files)
   * [5.1 General Rules](5_source_files/README.md#51-general-rules)
   * [5.2 Spacing](5_source_files/52_spacing.md#52-spacing)
