> On Aug 11, 2017, at 1:45 PM, Jordan Justen <jordan.l.jus...@intel.com> wrote:
> 
> 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 <ard.biesheu...@linaro.org>
>> Cc: Jordan Justen <jordan.l.jus...@intel.com>
>> Cc: Leif Lindholm <leif.lindh...@linaro.org>
>> Cc: Michael D Kinney <michael.d.kin...@intel.com>
>> Contributed-under: TianoCore Contribution Agreement 1.1
>> Signed-off-by: Laszlo Ersek <ler...@redhat.com>
>> ---
>> 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
>> 
>> If a function call or function like macro invocation is broken up into 
>> multiple
>> -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 
>> complex
>> +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 
>> argument
>> +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 = gBS->AllocatePool (EfiBootServicesData, sizeof 
>> (DRIVER_NAME_INSTANCE),
>> +                &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 = gBS->AllocatePool (
>                  EfiBootServicesData, sizeof (DRIVER_NAME_INSTANCE),
>                  &PrivateData);
> 

I like using as much width as allowed, but then again I've got 3440 X 1440 
monitors I'm using all the time. 

Another place that multiple things on the same line make sense is 
InstallMultipleProtocolInterfaces. I think that makes the code more readable. 

Status - gBS->InstallMultipleProtocolInterfaces (
                NULL,
                &gEdk2Protocol1Guid,                            
&gEdk2Protocol1Data, 
                &gEdk2Protocol2WithLongNameGuid,        
&gEdk2Protocol2WithLongNameData, 
                NULL
                );

Given a lot of this stuff is arbitrary (I had fun on the 1st coding standard 
doc) I think staying with what a lot of the code already does is not a bad idea.

Thanks,

Andrew Fish


> 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 items
>> 
>> 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=425) 
>> [CCS] clarify line breaking and indentation requirements for multi-line 
>> function 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
> _______________________________________________
> edk2-devel mailing list
> edk2-devel@lists.01.org <mailto:edk2-devel@lists.01.org>
> https://lists.01.org/mailman/listinfo/edk2-devel 
> <https://lists.01.org/mailman/listinfo/edk2-devel>
_______________________________________________
edk2-devel mailing list
edk2-devel@lists.01.org
https://lists.01.org/mailman/listinfo/edk2-devel

Reply via email to