From nobody Tue Dec 24 01:51:38 2024 Delivered-To: importer@patchew.org Authentication-Results: mx.zohomail.com; spf=none (zoho.com: 198.145.21.10 is neither permitted nor denied by domain of lists.01.org) smtp.mailfrom=edk2-devel-bounces@lists.01.org Return-Path: Received: from ml01.01.org (ml01.01.org [198.145.21.10]) by mx.zohomail.com with SMTPS id 1514978595037549.9475414670634; Wed, 3 Jan 2018 03:23:15 -0800 (PST) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id CF095222A54F9; Wed, 3 Jan 2018 03:18:00 -0800 (PST) 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 X-Original-To: edk2-devel@lists.01.org Received-SPF: none (zoho.com: 198.145.21.10 is neither permitted nor denied by domain of lists.01.org) client-ip=198.145.21.10; envelope-from=edk2-devel-bounces@lists.01.org; helo=ml01.01.org; 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 From: evan.lloyd@arm.com To: edk2-devel@lists.01.org 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] [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: , Cc: "Matteo.Carlini@arm.com"@arm.com, "nd@arm.com"@arm.com, "ard.biesheuvel@linaro.org"@arm.com, "lersek@redhat.com"@arm.com, "jordan.l.justen@intel.com"@arm.com, "liming.gao@intel.com"@arm.com, "leif.lindholm@linaro.org"@arm.com, "michael.d.kinney@intel.com"@arm.com MIME-Version: 1.0 Content-Transfer-Encoding: quoted-printable Errors-To: edk2-devel-bounces@lists.01.org Sender: "edk2-devel" X-ZohoMail: RSF_4 Z_629925259 SPT_0 Content-Type: text/plain; charset="utf-8" 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..1a9cd008b5dbbf203148408f92f= fb4881f499766 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 y= ou -define an Event. People will get confused. Make sure someone reading the c= ode -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 a= lways -reserved.** - -This includes macros, typedefs, variables, and functions, whether with ext= ernal -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 Keywo= rds". - -### 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 u= sed. -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 us= ing file. - -Any abbreviation used, which is not documented in this specification, or i= n the -_UEFI Specification_ shall be placed into a Glossary section of the File h= eader -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, be= cause -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 o= f 2 -(KiB for 2^10, MiB for 2^20, GiB for 2^30, etc.) rather than the old KB, M= B, -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 documentati= on - -##### 4.1.4.2.1 Translation tables are required for each module using a cr= eated 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 nam= ing -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 resour= ce -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 th= eir industry standard use. - -For example, use "PCI" in comments and documentation, and "Pci" for functi= ons, -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 Int= erchange | -| ATA | Ata | Advanced Technology Attachment = | -| ATAPI | Atapi | Advanced Technology Attachment Packet Inte= rface | -| 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 y= ou +define an Event. People will get confused. Make sure someone reading the c= ode +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 a= lways +reserved.** + +This includes macros, typedefs, variables, and functions, whether with ext= ernal +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 Keywo= rds". + +### 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 u= sed. +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 us= ing file. + +Any abbreviation used, which is not documented in this specification, or i= n the +_UEFI Specification_ shall be placed into a Glossary section of the File h= eader +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, be= cause +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 o= f 2 +(KiB for 2^10, MiB for 2^20, GiB for 2^30, etc.) rather than the old KB, M= B, +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 documentati= on + +##### 4.1.4.2.1 Translation tables are required for each module using a cr= eated 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 nam= ing +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 resour= ce +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 th= eir industry standard use. + +For example, use "PCI" in comments and documentation, and "Pci" for functi= ons, +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 Int= erchange | +| ATA | Ata | Advanced Technology Attachment = | +| ATAPI | Atapi | Advanced Technology Attachment Packet Inte= rface | +| 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 = | --=20 Guid("CE165669-3EF3-493F-B85D-6190EE5B9759") _______________________________________________ edk2-devel mailing list edk2-devel@lists.01.org https://lists.01.org/mailman/listinfo/edk2-devel