public inbox for devel@edk2.groups.io
 help / color / mirror / Atom feed
* [edk2-CCodingStandardsSpecification PATCH V2] Clarify format of multi-line function calls
@ 2017-06-12 21:39 Michael Kinney
  2017-06-12 21:39 ` Michael Kinney
  0 siblings, 1 reply; 3+ messages in thread
From: Michael Kinney @ 2017-06-12 21:39 UTC (permalink / raw)
  To: edk2-devel; +Cc: Laszlo Ersek, Jordan Justen, Liming Gao, Kevin W Shaw

https://bugzilla.tianocore.org/show_bug.cgi?id=425

GitHub branch for review:

* https://github.com/mdkinney/edk2-CCodingStandardsSpecification/tree/Bugzilla_425_ClarifyMultiLineFunctionCallFormat_V2

GitHub word diff view of the patches in this series:

* [1/1] https://github.com/mdkinney/edk2-CCodingStandardsSpecification/commit/880dd46e2068a06c87df128aa4955735ec7a07dc?w=1

Cc: Laszlo Ersek <lersek@redhat.com>
Cc: Jordan Justen <jordan.l.justen@intel.com>
Cc: Liming Gao <liming.gao@intel.com>
Cc: Kevin W Shaw <kevin.w.shaw@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Michael Kinney <michael.d.kinney@intel.com>

Michael Kinney (1):
  Clarify format of multi-line function calls

 5_source_files/52_spacing.md | 34 ++++++++++++++++------
 README.md                    | 69 ++++++++++++++++++++++----------------------
 2 files changed, 60 insertions(+), 43 deletions(-)

-- 
2.6.3.windows.1



^ permalink raw reply	[flat|nested] 3+ messages in thread

* [edk2-CCodingStandardsSpecification PATCH V2] Clarify format of multi-line function calls
  2017-06-12 21:39 [edk2-CCodingStandardsSpecification PATCH V2] Clarify format of multi-line function calls Michael Kinney
@ 2017-06-12 21:39 ` Michael Kinney
  2017-06-12 21:50   ` Laszlo Ersek
  0 siblings, 1 reply; 3+ messages in thread
From: Michael Kinney @ 2017-06-12 21:39 UTC (permalink / raw)
  To: edk2-devel; +Cc: Laszlo Ersek, Jordan Justen, Liming Gao, Kevin W Shaw

https://bugzilla.tianocore.org/show_bug.cgi?id=425

Cc: Laszlo Ersek <lersek@redhat.com>
Cc: Jordan Justen <jordan.l.justen@intel.com>
Cc: Liming Gao <liming.gao@intel.com>
Cc: Kevin W Shaw <kevin.w.shaw@intel.com>
Contributed-under: TianoCore Contribution Agreement 1.1
Signed-off-by: Michael Kinney <michael.d.kinney@intel.com>
---
 5_source_files/52_spacing.md | 34 ++++++++++++++++------
 README.md                    | 69 ++++++++++++++++++++++----------------------
 2 files changed, 60 insertions(+), 43 deletions(-)

diff --git a/5_source_files/52_spacing.md b/5_source_files/52_spacing.md
index 01f79b4..88e3eed 100644
--- a/5_source_files/52_spacing.md
+++ b/5_source_files/52_spacing.md
@@ -130,23 +130,39 @@ if (MyVar != 0) {
 If ((--MyInteger) > 0) {
 ```
 
-#### 5.2.2.4 Subsequent lines of multi-line function calls should line up one or two tabstops from the beginning of the function name
+#### 5.2.2.4 Subsequent lines of multi-line function calls should line up two spaces from the beginning of the function name
 
-Use either one or two tab stops to ensure that each parameter is indented at
-least two spaces after the function name. Either of the below examples is
-acceptable:
+If a function call or function like macro invocation is broken up into multiple
+lines, then:
+
+* 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
+  function is called through a structure or union member, of type
+  function-to-pointer, then indent each argument 2 spaces from the start of the
+  member name.
+* Align the close parenthesis with the start of the last argument
 
 ```c
+CopyMem (
+  Destination,
+  Source,
+  SIZE_4KB
+  );
+
 Status = gBS->AllocatePool (
                 EfiBootServicesData,
                 sizeof (DRIVER_NAME_INSTANCE),
                 &PrivateData
                 );
-Status = gBS->AllocatePool (
-                EfiBootServicesData,
-                sizeof (DRIVER_NAME_INSTANCE),
-                &PrivateData
-                );
+
+DEBUG ((
+  DEBUG_INFO,
+  "The addresses of the 4 buffers are %p, %p, %p, and %p",
+  Buffer1,
+  Buffer2,
+  Buffer3,
+  Buffer4
+  ));
 ```
 
 #### 5.2.2.5 Always put space after commas or semicolons that separate items
diff --git a/README.md b/README.md
index fb5fb0a..8b9675b 100644
--- a/README.md
+++ b/README.md
@@ -77,37 +77,38 @@ Copyright (c) 2006-2017, Intel Corporation. All rights reserved.
 
 ### Revision History
 
-| Revision   | Revision History                                                                                     | Date       |
-| ---------- | ---------------------------------------------------------------------------------------------------- | ---------- |
-| 0.0.1      | First swag.                                                                                          | 6/23/00    |
-| 0.0.2      | Included feedback from team.                                                                         | 8/3/00     |
-| 0.3        | Add comments.                                                                                        | 8/10/00    |
-| 0.3001     | Pre-vacation update, need to sync with new numbering process.                                        | 9/11/00    |
-| 0.31       | Incorporated Sync 1 learnings.                                                                       | 12/12/00   |
-| 0.32       | Completed TAT ARs.                                                                                   | 6/8/01     |
-| 0.33       | Added goto rules.                                                                                    | 8/16/01    |
-| 0.34       | Updated to match driver and Runtime Lib.                                                             | 11/15/01   |
-| 0.9        | Updated to Intel(R) Platform Innovation Framework for EFI. Added checklist appendix.                 | 1/8/04     |
-| 0.91       | Completed editing and formatting pass.                                                               | 3/3/04     |
-| 0.92       | Updated the structure declaration rules: Added section 4.8 and modified the checklist in Appendix A. | 4/8/04     |
-| 0.93       | Added some minor clarifications in section 3.1, 4.5, 7.1, and 10.                                    | 9/14/04    |
-| 0.94       | Revised to accommodate Doxygen style commenting standards                                            | 3/1/06     |
-| 0.50       | Change to new numbering scheme. Incorporate Review Comments. Editing and formatting.                 | 4/21/06    |
-| 0.51       | Changed to EDK II.                                                                                   | 7/13/06    |
-| 0.52       | Update rules to clarify areas of misinterpretation. Add copyright formatting rules.                  | 2/09/2010  |
-| 0.60       | Re-organize document and update to current rules.                                                    | 2/15/2010  |
-| 0.70       | Release for Review                                                                                   | 3/1/2010   |
-| 0.95       | Review comments incorporated, Release to Tech Pubs for Finalization                                  | 3/10/2010  |
-| 1.00       | First full release                                                                                   | 3/15/2010  |
-| 1.01       | Restructure into book format.                                                                        | 12/08/2011 |
-| 1.02       | Incorporate suggestions and trackers                                                                 | 3/19/2012  |
-|            | Release For Review                                                                                   | 4/2/2012   |
-|            | Release                                                                                              | 4/16/2012  |
-| 1.03       | Update and incorporate requests and bug fixes. Remove "Intel Confidential" classification.           | 9/11/2014  |
-| 1.50       | Release for Review                                                                                   | 9/26/2014  |
-| 1.80       | Incorporate US Review Comments                                                                       | 10/10/2014 |
-| 1.85       | Incorporate PRC Review Comments                                                                      | 10/24/2014 |
-|            | Release for Extended US & PRC Review                                                                 | 10/28/2014 |
-| 2.0        | Release                                                                                              | 11/14/2014 |
-| 2.1        | DRAFT for REFORMAT                                                                                   | 10/30/2015 |
-| 2.2        | Convert to Gitbook                                                                                   | April 2017 |
+| Revision | Revision History                                                                                                                                  | Date       |
+| -------- | ------------------------------------------------------------------------------------------------------------------------------------------------- | ---------- |
+| 0.0.1    | First swag.                                                                                                                                       | 6/23/00    |
+| 0.0.2    | Included feedback from team.                                                                                                                      | 8/3/00     |
+| 0.3      | Add comments.                                                                                                                                     | 8/10/00    |
+| 0.3001   | Pre-vacation update, need to sync with new numbering process.                                                                                     | 9/11/00    |
+| 0.31     | Incorporated Sync 1 learnings.                                                                                                                    | 12/12/00   |
+| 0.32     | Completed TAT ARs.                                                                                                                                | 6/8/01     |
+| 0.33     | Added goto rules.                                                                                                                                 | 8/16/01    |
+| 0.34     | Updated to match driver and Runtime Lib.                                                                                                          | 11/15/01   |
+| 0.9      | Updated to Intel(R) Platform Innovation Framework for EFI. Added checklist appendix.                                                              | 1/8/04     |
+| 0.91     | Completed editing and formatting pass.                                                                                                            | 3/3/04     |
+| 0.92     | Updated the structure declaration rules: Added section 4.8 and modified the checklist in Appendix A.                                              | 4/8/04     |
+| 0.93     | Added some minor clarifications in section 3.1, 4.5, 7.1, and 10.                                                                                 | 9/14/04    |
+| 0.94     | Revised to accommodate Doxygen style commenting standards                                                                                         | 3/1/06     |
+| 0.50     | Change to new numbering scheme. Incorporate Review Comments. Editing and formatting.                                                              | 4/21/06    |
+| 0.51     | Changed to EDK II.                                                                                                                                | 7/13/06    |
+| 0.52     | Update rules to clarify areas of misinterpretation. Add copyright formatting rules.                                                               | 2/09/2010  |
+| 0.60     | Re-organize document and update to current rules.                                                                                                 | 2/15/2010  |
+| 0.70     | Release for Review                                                                                                                                | 3/1/2010   |
+| 0.95     | Review comments incorporated, Release to Tech Pubs for Finalization                                                                               | 3/10/2010  |
+| 1.00     | First full release                                                                                                                                | 3/15/2010  |
+| 1.01     | Restructure into book format.                                                                                                                     | 12/08/2011 |
+| 1.02     | Incorporate suggestions and trackers                                                                                                              | 3/19/2012  |
+|          | Release For Review                                                                                                                                | 4/2/2012   |
+|          | Release                                                                                                                                           | 4/16/2012  |
+| 1.03     | Update and incorporate requests and bug fixes. Remove "Intel Confidential" classification.                                                        | 9/11/2014  |
+| 1.50     | Release for Review                                                                                                                                | 9/26/2014  |
+| 1.80     | Incorporate US Review Comments                                                                                                                    | 10/10/2014 |
+| 1.85     | Incorporate PRC Review Comments                                                                                                                   | 10/24/2014 |
+|          | Release for Extended US & PRC Review                                                                                                              | 10/28/2014 |
+| 2.0      | Release                                                                                                                                           | 11/14/2014 |
+| 2.1      | DRAFT for REFORMAT                                                                                                                                | 10/30/2015 |
+| 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 |            |
-- 
2.6.3.windows.1



^ permalink raw reply related	[flat|nested] 3+ messages in thread

* Re: [edk2-CCodingStandardsSpecification PATCH V2] Clarify format of multi-line function calls
  2017-06-12 21:39 ` Michael Kinney
@ 2017-06-12 21:50   ` Laszlo Ersek
  0 siblings, 0 replies; 3+ messages in thread
From: Laszlo Ersek @ 2017-06-12 21:50 UTC (permalink / raw)
  To: Michael Kinney, edk2-devel; +Cc: Jordan Justen, Liming Gao, Kevin W Shaw

On 06/12/17 23:39, Michael Kinney wrote:

> +* 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
> +  function is called through a structure or union member, of type
> +  function-to-pointer, then indent each argument 2 spaces from the start of the

I think we should say "pointer-to-function" here, not "function-to-pointer".

> +DEBUG ((
> +  DEBUG_INFO,
> +  "The addresses of the 4 buffers are %p, %p, %p, and %p",
> +  Buffer1,
> +  Buffer2,
> +  Buffer3,
> +  Buffer4
> +  ));
>  ```

Just to be consistent with actual code, I suggest appending "\n" to the
format string.

With those:

Reviewed-by: Laszlo Ersek <lersek@redhat.com>

Thanks!
Laszlo


^ permalink raw reply	[flat|nested] 3+ messages in thread

end of thread, other threads:[~2017-06-12 21:49 UTC | newest]

Thread overview: 3+ messages (download: mbox.gz follow: Atom feed
-- links below jump to the message on this page --
2017-06-12 21:39 [edk2-CCodingStandardsSpecification PATCH V2] Clarify format of multi-line function calls Michael Kinney
2017-06-12 21:39 ` Michael Kinney
2017-06-12 21:50   ` Laszlo Ersek

This is a public inbox, see mirroring instructions
for how to clone and mirror all data and code used for this inbox