From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received-SPF: Pass (sender SPF authorized) identity=mailfrom; client-ip=217.140.96.140; helo=cam-smtp0.cambridge.arm.com; envelope-from=evan.lloyd@arm.com; receiver=edk2-devel@lists.01.org Received: from cam-smtp0.cambridge.arm.com (fw-tnat.cambridge.arm.com [217.140.96.140]) (using TLSv1 with cipher AES256-SHA (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id F32F3222A54E5 for ; Wed, 3 Jan 2018 03:17:56 -0800 (PST) Received: from E111747.Emea.Arm.com (e111747.emea.arm.com [10.1.27.84]) by cam-smtp0.cambridge.arm.com (8.13.8/8.13.8) with ESMTP id w03BMrgn021422; Wed, 3 Jan 2018 11:22:54 GMT From: evan.lloyd@arm.com To: edk2-devel@lists.01.org Cc: "ard.biesheuvel@linaro.org"@arm.com, "leif.lindholm@linaro.org"@arm.com, "Matteo.Carlini@arm.com"@arm.com, "lersek@redhat.com"@arm.com, "liming.gao@intel.com"@arm.com, "michael.d.kinney@intel.com"@arm.com, "jordan.l.justen@intel.com"@arm.com, "nd@arm.com"@arm.com Date: Wed, 3 Jan 2018 11:22:47 +0000 Message-Id: <20180103112248.11880-5-evan.lloyd@arm.com> X-Mailer: git-send-email 2.14.1 In-Reply-To: <20180103112248.11880-1-evan.lloyd@arm.com> References: <20180103112248.11880-1-evan.lloyd@arm.com> Subject: [edk2-CCodingStandardsSpecification PATCH 4/5] Fix Chapter 4 Typo X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.23 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , X-List-Received-Date: Wed, 03 Jan 2018 11:17:58 -0000 From: Evan Lloyd 4.1.3.2 - remove "See" from 'as specified in See "File Heading"' Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Evan Lloyd --- 4_naming_conventions/README.md | 418 ++++++++++---------- 1 file changed, 209 insertions(+), 209 deletions(-) diff --git a/4_naming_conventions/README.md b/4_naming_conventions/README.md index bcf902875719f94c5c4c3e58af24e18772dae055..1a9cd008b5dbbf203148408f92ffb4881f499766 100644 --- a/4_naming_conventions/README.md +++ b/4_naming_conventions/README.md @@ -1,209 +1,209 @@ - - -# 4 Naming Conventions - -## 4.1 General Naming Rules - -**Use good naming practice when declaring variable names.** - -Studies show that programs with names averaging 10 to 16 characters are the -easiest to debug. The name length is just a guideline_; the most important -thing is that the name conveys a clear meaning of what it represents_. - -**Do not overload commonly used terms.** - -For example, EFI has an event model, so don't call some abstraction that you -define an Event. People will get confused. Make sure someone reading the code -can tell what you are talking about. - -**Each word or concept must start with a capital letter and be followed by -lower-case letters.** - -The intent is for names to be consistent and easily readable. Each word in a -compound name should be visually distinct. - -### 4.1.1 Identifiers that are always reserved - -**Identifiers beginning with an underscore are always reserved** - -Define them only in the special ways allowed elsewhere in this document. - -**Identifiers that are defined in the Standard C and POSIX libraries are always -reserved.** - -This includes macros, typedefs, variables, and functions, whether with external -linkage or file scope. The only exception is with modules that are mutually -exclusive with these libraries. These reserved identifiers are listed in -"Reserved Identifiers" and reserved keywords are listed in "Reserved Keywords". - -### 4.1.2 Common Opposites in Variable Names - -Use the correct opposites when declaring names. - -###### Table 1 Common Opposites - -| | | | -| --------------------- | --------------- | ---------------- | -| add / remove | begin / end | create / destroy | -| increment / decrement | first / last | get / release | -| lock / unlock | put / get | up / down | -| old / new | min / max | next / previous | -| source / destination | open / close | show / hide | -| | source / target | start / stop | - -### 4.1.3 Abbreviation Usage - -#### 4.1.3.1 The use of abbreviations shall be regulated. - -This document describes a common set of abbreviations that can be freely used. -If you must make up abbreviations, remember the name is most important to the -reader of the code, not the writer. - -#### 4.1.3.2 New abbreviations must be documented in the header of each using file. - -Any abbreviation used, which is not documented in this specification, or in the -_UEFI Specification_ shall be placed into a Glossary section of the File header -as specified in See "File Heading". - -Do not define a new abbreviation to replace an abbreviation that is already -defined in this document. For example, do not define No to mean Number, because -Num is the supported abbreviation. - -"EFI Supported Abbreviations" below lists the abbreviations that are -standardized by this document and do not require a defining comment. - -###### Table 2 EFI Supported Abbreviations - -| Abbreviation | Description | -| ------------ | ----------------------- | -| Ptr | Pointer | -| Str | Unicode string | -| Ascii | ASCII string | -| Len | Length | -| Arg | Argument | -| Max | Maximum | -| Min | Minimum | -| Char | Character | -| Num | Number | -| Temp | Temporary | -| Src | Source | -| Dst | Destination | -| BS | EFI Boot Services Table | -| RT | EFI Runtime Table | -| ST | EFI System Table | -| Tpl | EFI Task Priority Level | - -#### 4.1.3.3 Powers of 2 and 10 - -You are encouraged to use the IEC international abbreviations for powers of 2 -(KiB for 2^10, MiB for 2^20, GiB for 2^30, etc.) rather than the old KB, MB, -and GB, which IEC now reserves for powers of 10 (10^3, 10^6, 10^9). Given that -many readers of the code may not have made the conversion to add the 'i', do -not use KB, MB, and GB for powers of 10 Instead, use e.g. "2*10^6 bytes" -instead of 2MB to avoid confusion. Note that GiB is derived from the G in -'Giga', the 'i' in binary, and the B in 'Byte'. - -### 4.1.4 Acronym Usage - -#### 4.1.4.1 The use of acronyms shall be limited. - -Please remember the golden rule: Code for the person who will have to read and -maintain your code. Making up your own vocabulary to describe your module can -lead to lots of confusion. - -#### 4.1.4.2 Created Acronyms must be fully defined. - -If you must create acronyms, they must be fully defined in the documentation - -##### 4.1.4.2.1 Translation tables are required for each module using a created acronym - -Each module that uses the acronym must contain a translation table comment in -the file header. This definition is required so that others can understand your -names and comments. - -#### 4.1.4.3 Industry-Standard Acronyms are allowed - -It's okay to use acronyms for industry standards. - -Acronyms such as Pci, Acpi, Smbios, Isa, (capitalized per the variable naming -convention) are all legal to use without defining their meaning. - -If you reference an industry standard acronym, the file header must define to -which version of the specification the code is written. Thus, a PCI resource -manager would state that it was coded to follow the PCI 2.2 Specification and -which optional features it included support for. - -#### 4.1.4.4 Capitalize Acronyms in comments and documentation to match their industry standard use. - -For example, use "PCI" in comments and documentation, and "Pci" for functions, -files, etc. - -The table below lists the acronyms that are considered integral to the EDK II -vernacular, and may be used without defining their meaning in a comment. - -###### Table 3 EFI Supported Acronyms - -| Acronyms | In an Identifier | Description | -| -------- | ---------------- | -------------------------------------------------- | -| ACPI | Acpi | Advanced Configuration and Power Interface | -| AGP | Agp | Accelerated Graphics Port | -| ANSI | Ansi | American National Standards Institute | -| ASCII | Ascii | American Standard Code for Information Interchange | -| ATA | Ata | Advanced Technology Attachment | -| ATAPI | Atapi | Advanced Technology Attachment Packet Interface | -| BFD | Bfd | Boot Flash Device | -| BIOS | Bios | Basic Input/Output System | -| BIS | Bis | Boot Integrity Services | -| CMOS | Cmos | Complementary metal oxide semiconductor | -| CPU | Cpu | Central processing unit | -| CRC | Crc | Cyclic Redundancy Check | -| DMA | Dma | Direct Memory Access | -| DXE | Dxe | Driver Execution Environment | -| EFI | Efi | Extensible Firmware Interface | -| FD | Fd | Flash Device | -| FIFO | Fifo | First In First Out | -| FV | Fv | Firmware Volume | -| GUID | Guid | Globally Unique Identifier | -| IEC | Iec | International Electrotechnical Commission | -| ISA | Isa | Industry Standard Architecture | -| ISO | Iso | International Standards Organization | -| NVRAM | Nvram | Nonvolatile Random Access Memory | -| PCI | Pci | Peripheral Component Interconnect | -| PEI | Pei | Pre-EFI Initialization environment | -| RAM | Ram | Random Access Memory | -| ROM | Rom | Read-Only Memory | -| SRAM | Sram | Static Random Access Memory | -| TPL | Tpl | Task Priority Level | -| UEFI | Uefi | Unified Extensible Firmware Interface | -| UNDI | Undi | Universal Network Driver Interface | -| USB | Usb | Universal Serial Bus | -| VGA | Vga | Video graphics array | + + +# 4 Naming Conventions + +## 4.1 General Naming Rules + +**Use good naming practice when declaring variable names.** + +Studies show that programs with names averaging 10 to 16 characters are the +easiest to debug. The name length is just a guideline_; the most important +thing is that the name conveys a clear meaning of what it represents_. + +**Do not overload commonly used terms.** + +For example, EFI has an event model, so don't call some abstraction that you +define an Event. People will get confused. Make sure someone reading the code +can tell what you are talking about. + +**Each word or concept must start with a capital letter and be followed by +lower-case letters.** + +The intent is for names to be consistent and easily readable. Each word in a +compound name should be visually distinct. + +### 4.1.1 Identifiers that are always reserved + +**Identifiers beginning with an underscore are always reserved** + +Define them only in the special ways allowed elsewhere in this document. + +**Identifiers that are defined in the Standard C and POSIX libraries are always +reserved.** + +This includes macros, typedefs, variables, and functions, whether with external +linkage or file scope. The only exception is with modules that are mutually +exclusive with these libraries. These reserved identifiers are listed in +"Reserved Identifiers" and reserved keywords are listed in "Reserved Keywords". + +### 4.1.2 Common Opposites in Variable Names + +Use the correct opposites when declaring names. + +###### Table 1 Common Opposites + +| | | | +| --------------------- | --------------- | ---------------- | +| add / remove | begin / end | create / destroy | +| increment / decrement | first / last | get / release | +| lock / unlock | put / get | up / down | +| old / new | min / max | next / previous | +| source / destination | open / close | show / hide | +| | source / target | start / stop | + +### 4.1.3 Abbreviation Usage + +#### 4.1.3.1 The use of abbreviations shall be regulated. + +This document describes a common set of abbreviations that can be freely used. +If you must make up abbreviations, remember the name is most important to the +reader of the code, not the writer. + +#### 4.1.3.2 New abbreviations must be documented in the header of each using file. + +Any abbreviation used, which is not documented in this specification, or in the +_UEFI Specification_ shall be placed into a Glossary section of the File header +as specified in "File Heading". + +Do not define a new abbreviation to replace an abbreviation that is already +defined in this document. For example, do not define No to mean Number, because +Num is the supported abbreviation. + +"EFI Supported Abbreviations" below lists the abbreviations that are +standardized by this document and do not require a defining comment. + +###### Table 2 EFI Supported Abbreviations + +| Abbreviation | Description | +| ------------ | ----------------------- | +| Ptr | Pointer | +| Str | Unicode string | +| Ascii | ASCII string | +| Len | Length | +| Arg | Argument | +| Max | Maximum | +| Min | Minimum | +| Char | Character | +| Num | Number | +| Temp | Temporary | +| Src | Source | +| Dst | Destination | +| BS | EFI Boot Services Table | +| RT | EFI Runtime Table | +| ST | EFI System Table | +| Tpl | EFI Task Priority Level | + +#### 4.1.3.3 Powers of 2 and 10 + +You are encouraged to use the IEC international abbreviations for powers of 2 +(KiB for 2^10, MiB for 2^20, GiB for 2^30, etc.) rather than the old KB, MB, +and GB, which IEC now reserves for powers of 10 (10^3, 10^6, 10^9). Given that +many readers of the code may not have made the conversion to add the 'i', do +not use KB, MB, and GB for powers of 10 Instead, use e.g. "2*10^6 bytes" +instead of 2MB to avoid confusion. Note that GiB is derived from the G in +'Giga', the 'i' in binary, and the B in 'Byte'. + +### 4.1.4 Acronym Usage + +#### 4.1.4.1 The use of acronyms shall be limited. + +Please remember the golden rule: Code for the person who will have to read and +maintain your code. Making up your own vocabulary to describe your module can +lead to lots of confusion. + +#### 4.1.4.2 Created Acronyms must be fully defined. + +If you must create acronyms, they must be fully defined in the documentation + +##### 4.1.4.2.1 Translation tables are required for each module using a created acronym + +Each module that uses the acronym must contain a translation table comment in +the file header. This definition is required so that others can understand your +names and comments. + +#### 4.1.4.3 Industry-Standard Acronyms are allowed + +It's okay to use acronyms for industry standards. + +Acronyms such as Pci, Acpi, Smbios, Isa, (capitalized per the variable naming +convention) are all legal to use without defining their meaning. + +If you reference an industry standard acronym, the file header must define to +which version of the specification the code is written. Thus, a PCI resource +manager would state that it was coded to follow the PCI 2.2 Specification and +which optional features it included support for. + +#### 4.1.4.4 Capitalize Acronyms in comments and documentation to match their industry standard use. + +For example, use "PCI" in comments and documentation, and "Pci" for functions, +files, etc. + +The table below lists the acronyms that are considered integral to the EDK II +vernacular, and may be used without defining their meaning in a comment. + +###### Table 3 EFI Supported Acronyms + +| Acronyms | In an Identifier | Description | +| -------- | ---------------- | -------------------------------------------------- | +| ACPI | Acpi | Advanced Configuration and Power Interface | +| AGP | Agp | Accelerated Graphics Port | +| ANSI | Ansi | American National Standards Institute | +| ASCII | Ascii | American Standard Code for Information Interchange | +| ATA | Ata | Advanced Technology Attachment | +| ATAPI | Atapi | Advanced Technology Attachment Packet Interface | +| BFD | Bfd | Boot Flash Device | +| BIOS | Bios | Basic Input/Output System | +| BIS | Bis | Boot Integrity Services | +| CMOS | Cmos | Complementary metal oxide semiconductor | +| CPU | Cpu | Central processing unit | +| CRC | Crc | Cyclic Redundancy Check | +| DMA | Dma | Direct Memory Access | +| DXE | Dxe | Driver Execution Environment | +| EFI | Efi | Extensible Firmware Interface | +| FD | Fd | Flash Device | +| FIFO | Fifo | First In First Out | +| FV | Fv | Firmware Volume | +| GUID | Guid | Globally Unique Identifier | +| IEC | Iec | International Electrotechnical Commission | +| ISA | Isa | Industry Standard Architecture | +| ISO | Iso | International Standards Organization | +| NVRAM | Nvram | Nonvolatile Random Access Memory | +| PCI | Pci | Peripheral Component Interconnect | +| PEI | Pei | Pre-EFI Initialization environment | +| RAM | Ram | Random Access Memory | +| ROM | Rom | Read-Only Memory | +| SRAM | Sram | Static Random Access Memory | +| TPL | Tpl | Task Priority Level | +| UEFI | Uefi | Unified Extensible Firmware Interface | +| UNDI | Undi | Universal Network Driver Interface | +| USB | Usb | Universal Serial Bus | +| VGA | Vga | Video graphics array | -- Guid("CE165669-3EF3-493F-B85D-6190EE5B9759")