From nobody Thu May 2 12:50:39 2024 Delivered-To: importer@patchew.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; 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 1502470141382850.9350679046593; Fri, 11 Aug 2017 09:49:01 -0700 (PDT) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id 7D5A82095E016; Fri, 11 Aug 2017 09:46:39 -0700 (PDT) Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id 3C9CC2095E00F for ; Fri, 11 Aug 2017 09:46:37 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 62829C052449; Fri, 11 Aug 2017 16:48:57 +0000 (UTC) Received: from lacos-laptop-7.usersys.redhat.com (ovpn-116-239.phx2.redhat.com [10.3.116.239]) by smtp.corp.redhat.com (Postfix) with ESMTP id 0DC8B78DEF; Fri, 11 Aug 2017 16:48:55 +0000 (UTC) X-Original-To: edk2-devel@lists.01.org DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com 62829C052449 Authentication-Results: ext-mx08.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx08.extmail.prod.ext.phx2.redhat.com; spf=fail smtp.mailfrom=lersek@redhat.com From: Laszlo Ersek To: edk2-devel-01 Date: Fri, 11 Aug 2017 18:48:50 +0200 Message-Id: <20170811164851.9466-2-lersek@redhat.com> In-Reply-To: <20170811164851.9466-1-lersek@redhat.com> References: <20170811164851.9466-1-lersek@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.32]); Fri, 11 Aug 2017 16:48:57 +0000 (UTC) Subject: [edk2] [edk2-CCodingStandardsSpecification PATCH 1/2] Source Files / General Rules: limit line lengths to 80 columns X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.22 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Michael D Kinney , Jordan Justen , Leif Lindholm , Ard Biesheuvel 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" We currently say "stick with 80 if it's convenient, extend to 120 otherwise". This is too lax; much new edk2 code ignores the 80 columns recommendation, resulting in source files that are hard to read for some contributors. Remove the 120 columns excuse and make 80 columns a requirement. Cc: Ard Biesheuvel Cc: Jordan Justen Cc: Leif Lindholm Cc: Michael D Kinney Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Laszlo Ersek Reviewed-by: Jordan Justen Reviewed-by: Leif Lindholm --- 5_source_files/README.md | 17 ++++++++++++----- README.md | 1 + 2 files changed, 13 insertions(+), 5 deletions(-) diff --git a/5_source_files/README.md b/5_source_files/README.md index a93492db4f0f..546d44d94fcb 100644 --- a/5_source_files/README.md +++ b/5_source_files/README.md @@ -33,12 +33,19 @@ =20 ## 5.1 General Rules =20 -### 5.1.1 Lines shall be 120 columns, or less +### 5.1.1 Lines shall be 80 columns, or less =20 -Preferably, limit line lengths to 80 columns or less. When this doesn't le= ave -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. +Limit line lengths to 80 columns. + +Lines longer than 80 columns make it more difficult for the reader to find= the +beginning of the next line. They also tend to prevent users from displayin= g two +source listings side-by-side on common display devices. + +When the 80 columns limit doesn't leave sufficient space for a postfix sty= le +comment, break the line into shorter segments at logical boundaries (for +example, between the arguments of a function call, adhering to the spacing +rules), or replace the postfix style comment with a standalone comment that +precedes the statement. =20 ### 5.1.2 Do not use tab characters =20 diff --git a/README.md b/README.md index 8b9675b94937..8fad5a327b8c 100644 --- a/README.md +++ b/README.md @@ -112,3 +112,4 @@ Copyright (c) 2006-2017, Intel Corporation. All rights = reserved. | 2.1 | DRAFT for REFORMAT = = | 10/30/2015 | | 2.2 | Convert to Gitbook = = | June 2017 | | | [#425](https://bugzilla.tianocore.org/show_bug.cgi?id=3D425) = [CCS] clarify line breaking and indentation requirements for multi-line fun= ction calls | | +| | Limit lines to 80 columns = = | | --=20 2.13.1.3.g8be5a757fa67 _______________________________________________ edk2-devel mailing list edk2-devel@lists.01.org https://lists.01.org/mailman/listinfo/edk2-devel From nobody Thu May 2 12:50:39 2024 Delivered-To: importer@patchew.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; 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 1502470143880123.12566601259789; Fri, 11 Aug 2017 09:49:03 -0700 (PDT) Received: from [127.0.0.1] (localhost [IPv6:::1]) by ml01.01.org (Postfix) with ESMTP id B496A2095E01D; Fri, 11 Aug 2017 09:46:39 -0700 (PDT) Received: from mx1.redhat.com (mx1.redhat.com [209.132.183.28]) (using TLSv1.2 with cipher ECDHE-RSA-AES256-GCM-SHA384 (256/256 bits)) (No client certificate requested) by ml01.01.org (Postfix) with ESMTPS id DDED62095E00F for ; Fri, 11 Aug 2017 09:46:38 -0700 (PDT) Received: from smtp.corp.redhat.com (int-mx02.intmail.prod.int.phx2.redhat.com [10.5.11.12]) (using TLSv1.2 with cipher AECDH-AES256-SHA (256/256 bits)) (No client certificate requested) by mx1.redhat.com (Postfix) with ESMTPS id 17699356E6; Fri, 11 Aug 2017 16:48:59 +0000 (UTC) Received: from lacos-laptop-7.usersys.redhat.com (ovpn-116-239.phx2.redhat.com [10.3.116.239]) by smtp.corp.redhat.com (Postfix) with ESMTP id B907F78DEF; Fri, 11 Aug 2017 16:48:57 +0000 (UTC) X-Original-To: edk2-devel@lists.01.org DMARC-Filter: OpenDMARC Filter v1.3.2 mx1.redhat.com 17699356E6 Authentication-Results: ext-mx06.extmail.prod.ext.phx2.redhat.com; dmarc=none (p=none dis=none) header.from=redhat.com Authentication-Results: ext-mx06.extmail.prod.ext.phx2.redhat.com; spf=fail smtp.mailfrom=lersek@redhat.com From: Laszlo Ersek To: edk2-devel-01 Date: Fri, 11 Aug 2017 18:48:51 +0200 Message-Id: <20170811164851.9466-3-lersek@redhat.com> In-Reply-To: <20170811164851.9466-1-lersek@redhat.com> References: <20170811164851.9466-1-lersek@redhat.com> X-Scanned-By: MIMEDefang 2.79 on 10.5.11.12 X-Greylist: Sender IP whitelisted, not delayed by milter-greylist-4.5.16 (mx1.redhat.com [10.5.110.30]); Fri, 11 Aug 2017 16:48:59 +0000 (UTC) Subject: [edk2] [edk2-CCodingStandardsSpecification PATCH 2/2] Source Files / Spacing / Multi-line func. calls: allow condensed arguments X-BeenThere: edk2-devel@lists.01.org X-Mailman-Version: 2.1.22 Precedence: list List-Id: EDK II Development List-Unsubscribe: , List-Archive: List-Post: List-Help: List-Subscribe: , Cc: Michael D Kinney , Jordan Justen , Leif Lindholm , Ard Biesheuvel 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" The "one argument per line" style as the sole possibility takes up too much vertical space, wastes perfectly good horizontal space, and causes a constant jump-to-the-left eye movement for the reader. Now that we have limited the line length to 80 colums, the "condensed arguments" style cannot be abused; permit it. Cc: Ard Biesheuvel Cc: Jordan Justen Cc: Leif Lindholm Cc: Michael D Kinney Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Laszlo Ersek --- 5_source_files/52_spacing.md | 29 +++++++++++++++++++- README.md | 1 + 2 files changed, 29 insertions(+), 1 deletion(-) diff --git a/5_source_files/52_spacing.md b/5_source_files/52_spacing.md index ddeabf7753a8..fc8a5e7e58e7 100644 --- a/5_source_files/52_spacing.md +++ b/5_source_files/52_spacing.md @@ -133,7 +133,9 @@ If ((--MyInteger) > 0) { #### 5.2.2.4 Subsequent lines of multi-line function calls should line up = two spaces from the beginning of the function name =20 If a function call or function like macro invocation is broken up into mul= tiple -lines, then: +lines, then follow one of the alternatives below. + +##### 5.2.2.4.1 The "one argument per line" style =20 * One argument per line, including the first argument on its own line. * Indent each argument 2 spaces from the start of the function name. If a @@ -165,6 +167,31 @@ DEBUG (( )); ``` =20 +Use this line breaking style especially if it saves a format string or com= plex +argument from being split, or when commenting on individual arguments. + +##### 5.2.2.4.2 The "condensed arguments" style + +For most function calls and function-like macro invocations, the "one argu= ment +per line" style uses up valuable vertical space without utilizing readily +available horizontal space. Such statements are permitted to condense the +arguments and the closing parenthesis (or parentheses), up to the allowed = line +length. The indentation requirements are identical to those of the "one +argument per line" style. + +```c +CopyMem (Destination, Source, SIZE_4KB); + +Status =3D gBS->AllocatePool (EfiBootServicesData, sizeof (DRIVER_NAME_INS= TANCE), + &PrivateData); + +DEBUG ((DEBUG_INFO, "The addresses of the 4 buffers are %p, %p, %p, and %p= \n", + Buffer1, Buffer2, Buffer3, Buffer4)); +``` + +This line breaking style prevents overly frequent saccades to the left, wi= thout +resulting in overlong lines. + #### 5.2.2.5 Always put space after commas or semicolons that separate ite= ms =20 This punctuation is not necessary if no code or comments follow the comma = or diff --git a/README.md b/README.md index 8fad5a327b8c..437024e57677 100644 --- a/README.md +++ b/README.md @@ -113,3 +113,4 @@ Copyright (c) 2006-2017, Intel Corporation. All rights = reserved. | 2.2 | Convert to Gitbook = = | June 2017 | | | [#425](https://bugzilla.tianocore.org/show_bug.cgi?id=3D425) = [CCS] clarify line breaking and indentation requirements for multi-line fun= ction calls | | | | Limit lines to 80 columns = = | | +| | Introduce the "condensed arguments" line breaking style = = | | --=20 2.13.1.3.g8be5a757fa67 _______________________________________________ edk2-devel mailing list edk2-devel@lists.01.org https://lists.01.org/mailman/listinfo/edk2-devel