From mboxrd@z Thu Jan 1 00:00:00 1970 Return-Path: Received: from mga01.intel.com (mga01.intel.com [192.55.52.88]) (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 4CAE12095D8D3 for ; Fri, 11 Aug 2017 13:42:53 -0700 (PDT) Received: from orsmga002.jf.intel.com ([10.7.209.21]) by fmsmga101.fm.intel.com with ESMTP/TLS/DHE-RSA-AES256-GCM-SHA384; 11 Aug 2017 13:45:13 -0700 X-ExtLoop1: 1 X-IronPort-AV: E=Sophos;i="5.41,359,1498546800"; d="scan'208";a="122686413" Received: from ajblattn-mobl3.amr.corp.intel.com (HELO localhost) ([10.252.204.55]) by orsmga002.jf.intel.com with ESMTP; 11 Aug 2017 13:45:12 -0700 MIME-Version: 1.0 To: Laszlo Ersek , edk2-devel-01 Message-ID: <150248431260.29687.8219608274582743547@jljusten-skl> From: Jordan Justen In-Reply-To: <20170811164851.9466-3-lersek@redhat.com> Cc: Michael D Kinney , Leif Lindholm , Ard Biesheuvel References: <20170811164851.9466-1-lersek@redhat.com> <20170811164851.9466-3-lersek@redhat.com> User-Agent: alot/0.5.1 Date: Fri, 11 Aug 2017 13:45:12 -0700 Subject: Re: [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: , X-List-Received-Date: Fri, 11 Aug 2017 20:42:53 -0000 Content-Type: text/plain; charset="utf-8" Content-Transfer-Encoding: quoted-printable On 2017-08-11 09:48:51, Laszlo Ersek wrote: > 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 u= p two spaces from the beginning of the function name > = > If a function call or function like macro invocation is broken up into m= ultiple > -lines, then: > +lines, then follow one of the alternatives below. > + > +##### 5.2.2.4.1 The "one argument per line" style > = > * 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 (( > )); > ``` > = > +Use this line breaking style especially if it saves a format string or c= omplex > +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 ar= gument > +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 allowe= d 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_I= NSTANCE), > + &PrivateData); I prefer that we just have one style, and just drop the requirement that multiline param lists can only have one arg per line. I think it is good to have the first param start on the next line in this case. Status =3D gBS->AllocatePool ( EfiBootServicesData, sizeof (DRIVER_NAME_INSTANCE), &PrivateData); This compacts things somewhat, but still keeps the parameter list aligned horizontally on subsequent lines. Regarding the closing parens being on a separate line, I think we should also remove that as a requirement. I think you might want to break out the multiple params per line and closing parens change out to allow for separate discussion. -Jordan > + > +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, = without > +resulting in overlong lines. > + > #### 5.2.2.5 Always put space after commas or semicolons that separate i= tems > = > This punctuation is not necessary if no code or comments follow the comm= a 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 right= s 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 f= unction calls | | > | | Limit lines to 80 columns = = | | > +| | Introduce the "condensed arguments" line breaking style = = | | > -- = > 2.13.1.3.g8be5a757fa67 > = > _______________________________________________ > edk2-devel mailing list > edk2-devel@lists.01.org > https://lists.01.org/mailman/listinfo/edk2-devel