From nobody Mon Dec 23 19:12:16 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 1514978597820504.69647020920604; Wed, 3 Jan 2018 03:23:17 -0800 (PST) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id 287D0222A54FC; Wed, 3 Jan 2018 03:18:01 -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 E836E222A54EA for ; Wed, 3 Jan 2018 03:17:58 -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 w03BMrgk021422; 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:44 +0000 Message-Id: <20180103112248.11880-2-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 1/5] Fix Chapter 1 Typos 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 1.1 Abstract - replace "then" with "can" (to make meaningful) 1.2 Rationale - change "commit to conforming to standards of this specification" to commit to conforming with the standards of this specification 1.3 Scope - add missing "to" in "an attempt make you aware of your actions" Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Evan Lloyd --- 1_introduction.md | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/1_introduction.md b/1_introduction.md index c22c04c9f76d2352e4f294c0e70f5ebf787f7054..5471a6bf5e94df6dd0c5fd0a4b5= 020c77d1f8ca0 100644 --- a/1_introduction.md +++ b/1_introduction.md @@ -62,7 +62,7 @@ This specification addresses the chronic problem of provi= ding accurate documentation of the code base by embedding the documentation within the c= ode. While this does not guarantee that the documentation will be kept up to da= te, it significantly increases the chances. A document generation system, Doxy= gen, -then produce formatted documentation by extracting information from specia= lly +can produce formatted documentation by extracting information from special= ly formatted comment blocks and the syntactic elements of the code. =20 This specification presents protocol standards that will ensure that the @@ -97,10 +97,10 @@ wide support. On the downside in that each developer's = C code could lack of uniformity makes understanding and maintaining the code very diffi= cult. =20 Uniformity is the key theme of these rules. You may disagree with some of = our -decisions. Nevertheless, we ask that you commit to conforming to standards= of -this specification. Also, there are pitfalls inherent in the C language th= at -this style guide may help you to avoid. The goal of this document is making -you, and those who follow you, more productive. +decisions. Nevertheless, we ask that you commit to conforming with the +standards of this specification. Also, there are pitfalls inherent in the C +language that this style guide may help you to avoid. The goal of this doc= ument +is making you, and those who follow you, more productive. =20 Some of the strict rules for protocol and driver construction may seem ove= rly onerous. Don't panic - there is a method to our madness - we intend to @@ -161,7 +161,7 @@ Topics covered in this coding standard include: * Commenting rules * Doxygen =20 -These guidelines represent an attempt make you aware of your actions, beca= use +These guidelines represent an attempt to make you aware of your actions, b= ecause those actions affect the future readers and maintainers of the code you pr= oduce. =20 Pre-existing code ported to the EDK II environment does not have to confor= m to --=20 Guid("CE165669-3EF3-493F-B85D-6190EE5B9759") _______________________________________________ edk2-devel mailing list edk2-devel@lists.01.org https://lists.01.org/mailman/listinfo/edk2-devel From nobody Mon Dec 23 19:12:16 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 1514978591066255.58794109275573; Wed, 3 Jan 2018 03:23:11 -0800 (PST) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id 758D3222A54F6; 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 151B6222A54E9 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 w03BMrgl021422; 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:45 +0000 Message-Id: <20180103112248.11880-3-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 2/5] Fix Chapter 2 Typos 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 2.1 Accessibility - remove erroneous "as" 2.1 Confirmation - insert missing full stop 2.1 Forgiveness - excise superfluous "errors" 2.1 Standard techniques - remove redundant "be to" Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Evan Lloyd Reviewed-by: Laszlo Ersek --- 2_guiding_principles.md | 8 ++++---- 1 file changed, 4 insertions(+), 4 deletions(-) diff --git a/2_guiding_principles.md b/2_guiding_principles.md index a7759f27dcf71a948b903332c9bc14946e445cd8..5a51225b65dec2159a4fb944819= 20666c0d042ff 100644 --- a/2_guiding_principles.md +++ b/2_guiding_principles.md @@ -47,7 +47,7 @@ The following is an alphabetical list of software design = principles: **Accessibility** =20 This entails designing objects and environments to be usable, with no -modification, by the greatest number of people as possible, including peop= le +modification, by the greatest number of people possible, including people with varying educational and social backgrounds, as well as those with mot= or or sensory challenges. =20 @@ -68,7 +68,7 @@ shortterm memory, as well as to accommodate its limits. This is a technique used for critical actions, inputs, or commands. Confirmations are primarily used to prevent unintended actions. Minimize e= rrors in critical or irreversible operations with confirmations. If you overuse -confirmations, expect that they will be ignored Avoid overusing confirmati= ons +confirmations, expect that they will be ignored. Avoid overusing confirmat= ions to ensure that they remain unexpected and uncommon; otherwise, they may be ignored. Use a two-step operation for hardware confirmations and dialogs f= or software confirmations. @@ -97,7 +97,7 @@ about the assumptions you make. **Forgiveness** =20 Design to help users avoid errors and reduce the negative consequences of -errors any errors made. Recommended methods for achieving design forgivene= ss +any errors made. Recommended methods for achieving design forgiveness include affordances, reversibility of actions, and safety nets. Effectively designing for forgiveness results in a design needing minimal confirmation= s, warnings, and help. @@ -171,7 +171,7 @@ classes of platforms from embedded systems to massively= parallel computers. =20 Greater reliance on unique or exotic pieces makes a system harder to understand, and more intimidating for someone trying to understand it the = first -time. Using standardized, common approaches should be to give the whole sy= stem +time. Using standardized, common approaches should give the whole system a familiar feeling. This standardization is one of the primary goals of th= is document. =20 --=20 Guid("CE165669-3EF3-493F-B85D-6190EE5B9759") _______________________________________________ edk2-devel mailing list edk2-devel@lists.01.org https://lists.01.org/mailman/listinfo/edk2-devel From nobody Mon Dec 23 19:12:16 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 1514978584502431.6069048528283; Wed, 3 Jan 2018 03:23:04 -0800 (PST) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id 6FDCF222A54ED; Wed, 3 Jan 2018 03:17:59 -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 E0C5C22280C30 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 w03BMrgm021422; 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:46 +0000 Message-Id: <20180103112248.11880-4-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 3/5] Fix Chapter 3 Typos 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 3_quick_reference.md has some obviously invalid extra characters at the end of line 55 ( ",). This patch removes them. Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Evan Lloyd Reviewed-by: Laszlo Ersek --- 3_quick_reference.md | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/3_quick_reference.md b/3_quick_reference.md index 13045d297b3be848d91f9be05380454b4cc2fe91..9367e422fb0337007409d659791= 3cb43da92e0c5 100644 --- a/3_quick_reference.md +++ b/3_quick_reference.md @@ -55,7 +55,7 @@ any file using the abbreviation or acronym. See "Abbreviation Usage" and "Glossary". =20 -* There is no limit to name lengths. A length of 10 to 30 characters is ", +* There is no limit to name lengths. A length of 10 to 30 characters is recommended. See "File Names" & "Identifiers that are always reserved". =20 * File names must not start with numbers. See "File Names". --=20 Guid("CE165669-3EF3-493F-B85D-6190EE5B9759") _______________________________________________ edk2-devel mailing list edk2-devel@lists.01.org https://lists.01.org/mailman/listinfo/edk2-devel From nobody Mon Dec 23 19:12:16 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 From nobody Mon Dec 23 19:12:16 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 151497858842082.82544403999088; Wed, 3 Jan 2018 03:23:08 -0800 (PST) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id 2EA50222A54F3; 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 E46AF222A54E3 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 w03BMrgo021422; 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:48 +0000 Message-Id: <20180103112248.11880-6-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> MIME-Version: 1.0 Subject: [edk2] [edk2-CCodingStandardsSpecification PATCH 5/5] Fix Chapter 5 Typos 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 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable Errors-To: edk2-devel-bounces@lists.01.org Sender: "edk2-devel" X-ZohoMail: RSF_4 Z_629925259 SPT_0 From: Evan Lloyd 5.1.1 - Replace "less" with "fewer" (because columns is plural and countable) 5.1.5 - Correct tense. (because the C specification still defines...) Insert full stop. Insert comma. 5.1.8 - Correct "provided" to "proven". 5.1.9 - remove hanging "This." 5.2.3.1 - replace "is comprised of" with "comprises" (comprise means "consists of", so "comprised of" is a solecism. Remove use of tab, as they are forbidden. Remove -- before date in copyright header (None of the edk2 files have it). 5.4 - Add indent to comment text. 5.6.1.2 - Fix copy/paste text (from UEFI spec). Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Evan Lloyd --- 5_source_files/52_spacing.md | 9 +++++---- 5_source_files/54_code_file_structure.md | 4 ++-- 5_source_files/56_declarations_and_types.md | 4 ++-- 5_source_files/README.md | 18 +++++++++--------- 4 files changed, 18 insertions(+), 17 deletions(-) diff --git a/5_source_files/52_spacing.md b/5_source_files/52_spacing.md index ddeabf7753a8713bf04e143d6e2e9bccf881f691..3c79f4e4ee91bcd4035d6cf7d8d= 32f1bb9c7756f 100644 --- a/5_source_files/52_spacing.md +++ b/5_source_files/52_spacing.md @@ -249,7 +249,7 @@ And the comment will end with: **/ ``` =20 -The File Heading comment block is comprised of the following sections: File +The File Heading comment block comprises the following sections: File Description, Copyright, License, and the optional Specification Reference = and Glossary sections. =20 @@ -266,8 +266,9 @@ Glossary sections. **/ ``` =20 -The following example begins each body line with a tab (two spaces). This = is -the preferred indentation, but two tabs (four spaces) is also acceptable. +The following example begins each body line with an indent (two spaces). +This is the preferred indentation, but a double indent (four spaces) is al= so +acceptable. =20 #### Example =20 @@ -278,7 +279,7 @@ the preferred indentation, but two tabs (four spaces) i= s also acceptable. Detailed description of the file=E2=80=99s contents and other useful information for a person viewing the file for the first time. =20 - Copyright (C) --20XX, Acme Corporation. All rights reserved.
+ Copyright (C) 20XX, Acme Corporation. All rights reserved.
This program and the accompanying materials are licensed and made available under the terms and conditions of the BSD License which accompanies this distribution. The full diff --git a/5_source_files/54_code_file_structure.md b/5_source_files/54_c= ode_file_structure.md index 8cc9f4f61412b07f765d80d7b680c6dd38b838c1..ac999aae99ae9cfd8b6f97dc483= e51bfbd7c7a0b 100644 --- a/5_source_files/54_code_file_structure.md +++ b/5_source_files/54_code_file_structure.md @@ -68,8 +68,8 @@ these are C files with an extension of "`.c`". =20 /* Function Definitions */ =20 -/* If this is a protocol definition, the -protocol structure is defined and initialized here. +/* If this is a protocol definition, the protocol structure is defined and + initialized here. */ ``` =20 diff --git a/5_source_files/56_declarations_and_types.md b/5_source_files/5= 6_declarations_and_types.md index ec1803d980e1fa808b9dc515cdffbc4b47437435..5c57834fe1195b5487f0f59e8a0= 385e44d91aff4 100644 --- a/5_source_files/56_declarations_and_types.md +++ b/5_source_files/56_declarations_and_types.md @@ -43,9 +43,9 @@ or from common EFI data types. The corresponding EFI types must be used instead. =20 "EFI Data Types" below contains the common data types that are referenced = in -the interface definitions defined by this specification. Per the _UEFI -Specification_, version 2.3.1: +the interface definitions defined by the UEFI specification. =20 +Per the _UEFI Specification_, version 2.3.1: "Unless otherwise specified, all data types are naturally aligned. Structu= res are aligned on boundaries equal to the largest internal datum of the struc= ture, and internal data is implicitly padded to achieve natural alignment." diff --git a/5_source_files/README.md b/5_source_files/README.md index a93492db4f0f17e14d9c2c3c95e57cf0f6cc911e..a443148138f2abaf6b9131f4758= 858a4a5f45fd3 100644 --- a/5_source_files/README.md +++ b/5_source_files/README.md @@ -33,9 +33,9 @@ =20 ## 5.1 General Rules =20 -### 5.1.1 Lines shall be 120 columns, or less +### 5.1.1 Lines shall be 120 columns, or fewer =20 -Preferably, limit line lengths to 80 columns or less. When this doesn't le= ave +Preferably, limit line lengths to 80 columns or fewer. When this doesn't l= eave sufficient space for a good postfix style comment, extend the line to a to= tal of 120 columns. Having some level of uniformity in the expected width of t= he source is useful for viewing and printing the code. @@ -79,9 +79,9 @@ Other than '\0', the only permissible escape sequences ar= e: =20 ### 5.1.5 Octal constants (Base 8) shall not be used. =20 -The C language specification has defined numbers whose first digit is zero= as -octal, so 010 is decimal 8 The use of octal has declined considerably sinc= e C -was first defined but this construct remains for backwards compatibility. = Its +The C language specification defines numbers whose first digit is zero as +octal, so 010 is decimal 8. The use of octal has declined considerably sin= ce C +was first defined, but this construct remains for backwards compatibility.= Its use is prohibited. In particular, do not be tempted to use the zero prefix= in tables of numbers to ensure visual alignment: =20 @@ -107,16 +107,16 @@ Trigraphs are a construct to allow character represen= tations that do not support all ASCII characters to enter the equivalent of the ASCII characte= r. Trigraphs are three characters long (hence the "tri"). The first two chara= cters are "??" while the third character disambiguates the trigraph. Technically -therefore, a[5] could be written a??(5??). Trigraphs have provided both +therefore, a[5] could be written a??(5??). Trigraphs have proven both confusing and unnecessary and are prohibited. =20 ### 5.1.9 In-line assembler shall not be used =20 There are really no reasons for in-line assembler to be used in EDK II cod= e. The only exceptions in this case are largely associated with the lowest le= vel -Architectural Protocols. Using in-line assembly language deviates against = the -Scope rules defined in Section 1.3 "Scope" because it is an extension to -standard C. This. +Architectural Protocols. Using in-line assembly language deviates from the +Scope rules defined in Section 1.3 "Scope", because it is an extension to +standard C. =20 ### 5.1.10 Do not use #pragma, except for #pragma pack (#). =20 --=20 Guid("CE165669-3EF3-493F-B85D-6190EE5B9759") _______________________________________________ edk2-devel mailing list edk2-devel@lists.01.org https://lists.01.org/mailman/listinfo/edk2-devel