Thanks for addressing my comments 😊 Reviewed-by: Ray Ni <ray...@intel.com>
> -----Original Message----- > From: abner.ch...@amd.com <abner.ch...@amd.com> > Sent: Saturday, October 15, 2022 7:47 PM > To: devel@edk2.groups.io > Cc: Ni, Ray <ray...@intel.com>; Kinney, Michael D > <michael.d.kin...@intel.com>; Sunil V L <suni...@ventanamicro.com>; > Abdul Lateef Attar <abdat...@amd.com>; Leif Lindholm > <quic_llind...@quicinc.com> > Subject: [tianocore-docs][PATCH V2 1/2] edk II C Coding Standard: Insert > Directory Names section > > From: Abner Chang <abner.ch...@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.ch...@amd.com> > Cc: Ray Ni <ray...@intel.com> > Cc: Michael D Kinney <michael.d.kin...@intel.com> > Cc: Sunil V L <suni...@ventanamicro.com> > Cc: Abdul Lateef Attar <abdat...@amd.com> > Cc: Leif Lindholm <quic_llind...@quicinc.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 (#95308): https://edk2.groups.io/g/devel/message/95308 Mute This Topic: https://groups.io/mt/94344808/21656 Group Owner: devel+ow...@edk2.groups.io Unsubscribe: https://edk2.groups.io/g/devel/unsub [arch...@mail-archive.com] -=-=-=-=-=-=-=-=-=-=-=-
