[edk2-devel] [tianocore-docs][PATCH V3 1/2] edk II C Coding Standard: Insert Directory Names section
Chang, Abner via groups.io
abner.chang=amd.com at groups.io
Wed Oct 19 04:33:11 UTC 2022
From: Abner Chang <abner.chang at amd.com>
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 at amd.com>
Cc: Ray Ni <ray.ni at intel.com>
Cc: Michael D Kinney <michael.d.kinney at intel.com>
Cc: Sunil V L <sunilvl at ventanamicro.com>
Cc: Abdul Lateef Attar <abdattar at amd.com>
Cc: Leif Lindholm <quic_llindhol at quicinc.com>
Reviewed-by: Ray Ni <Ray.ni at intel.com>
Reviewed-by: Abdul Lateef Attar <abdattar at amd.com>
---
4_naming_conventions/42_directory_names.md | 30 +++++++++++++
.../{42_file_names.md => 43_file_names.md} | 12 +++---
.../{43_identifiers.md => 44_identifiers.md} | 42 +++++++++----------
...les.md => 45_global_&_module_variables.md} | 10 ++---
..._space_rules.md => 46_name_space_rules.md} | 18 ++++----
README.md | 1 +
SUMMARY.md | 12 +++---
7 files changed, 79 insertions(+), 46 deletions(-)
create mode 100644 4_naming_conventions/42_directory_names.md
rename 4_naming_conventions/{42_file_names.md => 43_file_names.md} (87%)
rename 4_naming_conventions/{43_identifiers.md => 44_identifiers.md} (85%)
rename 4_naming_conventions/{44_global_&_module_variables.md => 45_global_&_module_variables.md} (90%)
rename 4_naming_conventions/{45_name_space_rules.md => 46_name_space_rules.md} (87%)
diff --git a/4_naming_conventions/42_directory_names.md b/4_naming_conventions/42_directory_names.md
new file mode 100644
index 0000000..766ccb1
--- /dev/null
+++ 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/42_file_names.md b/4_naming_conventions/43_file_names.md
similarity index 87%
rename from 4_naming_conventions/42_file_names.md
rename to 4_naming_conventions/43_file_names.md
index f948763..13e0c63 100644
--- a/4_naming_conventions/42_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/43_identifiers.md b/4_naming_conventions/44_identifiers.md
similarity index 85%
rename from 4_naming_conventions/43_identifiers.md
rename to 4_naming_conventions/44_identifiers.md
index 5363f73..5c1b113 100644
--- a/4_naming_conventions/43_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,7 +42,7 @@ 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
@@ -50,9 +50,9 @@ 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/44_global_&_module_variables.md b/4_naming_conventions/45_global_&_module_variables.md
similarity index 90%
rename from 4_naming_conventions/44_global_&_module_variables.md
rename to 4_naming_conventions/45_global_&_module_variables.md
index a2ec4f6..cdeb0a2 100644
--- a/4_naming_conventions/44_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/45_name_space_rules.md b/4_naming_conventions/46_name_space_rules.md
similarity index 87%
rename from 4_naming_conventions/45_name_space_rules.md
rename to 4_naming_conventions/46_name_space_rules.md
index ecdebbe..98e2687 100644
--- a/4_naming_conventions/45_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
index 0648819..77cfdc8 100644
--- 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
index cf8600a..32a575d 100644
--- 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)
--
2.37.1.windows.1
-=-=-=-=-=-=-=-=-=-=-=-
Groups.io Links: You receive all messages sent to this group.
View/Reply Online (#95360): https://edk2.groups.io/g/devel/message/95360
Mute This Topic: https://groups.io/mt/94424835/1813853
Group Owner: devel+owner at edk2.groups.io
Unsubscribe: https://edk2.groups.io/g/devel/unsub [edk2-devel-archive at redhat.com]
-=-=-=-=-=-=-=-=-=-=-=-
More information about the edk2-devel-archive
mailing list