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 <[email protected]> Cc: Jordan Justen <[email protected]> Cc: Leif Lindholm <[email protected]> Cc: Michael D Kinney <[email protected]> Contributed-under: TianoCore Contribution Agreement 1.1 Signed-off-by: Laszlo Ersek <[email protected]> --- 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); + +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 [email protected] https://lists.01.org/mailman/listinfo/edk2-devel
