[edk2-CCodingStandardsSpecification PATCH 2/2] Source Files / Spacing / Multi-line func. calls: allow condensed arguments

[Laszlo Ersek <lersek@redhat.com>]

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.biesheuvel@linaro.org>
Cc: Jordan Justen <jordan.l.justen@intel.com>
Cc: Leif Lindholm <leif.lindholm@linaro.org>
Cc: Michael D Kinney <michael.d.kinney@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Laszlo Ersek <lersek@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);
+
+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