From 9ad0a65adb3766ff38ad9f99557cfdda151bfaaf Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 30 Oct 2023 10:45:33 +0100 Subject: [PATCH 1/9] PEP 7: Add C pre-processor macro style recommendations --- peps/pep-0007.rst | 17 +++++++++++++++++ 1 file changed, 17 insertions(+) diff --git a/peps/pep-0007.rst b/peps/pep-0007.rst index d88373f29b3..197b4b15139 100644 --- a/peps/pep-0007.rst +++ b/peps/pep-0007.rst @@ -135,6 +135,20 @@ Code lay-out return 0; /* "Forgive" adding a __dict__ only */ } +* Vertically align line continuation characters in multi-line macros. + +* Macros intended to be used as a statement should use the + ``do {... }while(0)``` macro idiom. + Example:: + + #define ADD_INT_MACRO(MOD, INT) do { \ + if (PyModule_AddIntConstant((MOD), (#INT), (INT)) < 0) { \ + goto error; \ + } \ + } while (0) + +* ``#undef`` macros after use. + * Put blank lines around functions, structure definitions, and major sections inside functions. @@ -170,6 +184,9 @@ Naming conventions * Macros should have a MixedCase prefix and then use upper case, for example: ``PyString_AS_STRING``, ``Py_PRINT_RAW``. +* Macro parameters should use ``ALL_CAPS`` style, + so they are easily distinguishable from C variables and struct members. + Documentation Strings ===================== From 46e32f5868d7ba73b8f4c980906d93a228783a15 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 30 Oct 2023 10:47:21 +0100 Subject: [PATCH 2/9] Remove extra backtick --- peps/pep-0007.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0007.rst b/peps/pep-0007.rst index 197b4b15139..3f52b01146e 100644 --- a/peps/pep-0007.rst +++ b/peps/pep-0007.rst @@ -138,7 +138,7 @@ Code lay-out * Vertically align line continuation characters in multi-line macros. * Macros intended to be used as a statement should use the - ``do {... }while(0)``` macro idiom. + ``do {... }while(0)`` macro idiom. Example:: #define ADD_INT_MACRO(MOD, INT) do { \ From 3522cbe6a90eae24871500f12cb7847594c35ad1 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 30 Oct 2023 10:48:20 +0100 Subject: [PATCH 3/9] Whitespace --- peps/pep-0007.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0007.rst b/peps/pep-0007.rst index 3f52b01146e..d9e28e28320 100644 --- a/peps/pep-0007.rst +++ b/peps/pep-0007.rst @@ -138,7 +138,7 @@ Code lay-out * Vertically align line continuation characters in multi-line macros. * Macros intended to be used as a statement should use the - ``do {... }while(0)`` macro idiom. + ``do {... } while(0)`` macro idiom. Example:: #define ADD_INT_MACRO(MOD, INT) do { \ From 57c310fc269185f5c39cf639dc4c5643ebfeaa70 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 30 Oct 2023 11:01:14 +0100 Subject: [PATCH 4/9] Address review: only recommend undef'ing private macros Co-authored-by: Antoine Pitrou --- peps/pep-0007.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0007.rst b/peps/pep-0007.rst index d9e28e28320..d696a8f728c 100644 --- a/peps/pep-0007.rst +++ b/peps/pep-0007.rst @@ -147,7 +147,7 @@ Code lay-out } \ } while (0) -* ``#undef`` macros after use. +* ``#undef`` private macros after use. * Put blank lines around functions, structure definitions, and major sections inside functions. From ce3a72b13a098bc3514c46ae3b1e336f6e42b84f Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Mon, 30 Oct 2023 12:54:28 +0100 Subject: [PATCH 5/9] Address review: be explicit regarding final semicolons --- peps/pep-0007.rst | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/peps/pep-0007.rst b/peps/pep-0007.rst index d696a8f728c..a9431964d61 100644 --- a/peps/pep-0007.rst +++ b/peps/pep-0007.rst @@ -138,7 +138,8 @@ Code lay-out * Vertically align line continuation characters in multi-line macros. * Macros intended to be used as a statement should use the - ``do {... } while(0)`` macro idiom. + ``do {... } while(0)`` macro idiom, + without a final semicolon. Example:: #define ADD_INT_MACRO(MOD, INT) do { \ From 31be7f224cec8d6b09a5aa20d913c87a9384e506 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 1 Nov 2023 11:15:44 +0100 Subject: [PATCH 6/9] Address review remarks - whitespace fixup - put the 'do {' on a separate line --- peps/pep-0007.rst | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/peps/pep-0007.rst b/peps/pep-0007.rst index a9431964d61..2becf29fc0b 100644 --- a/peps/pep-0007.rst +++ b/peps/pep-0007.rst @@ -138,11 +138,12 @@ Code lay-out * Vertically align line continuation characters in multi-line macros. * Macros intended to be used as a statement should use the - ``do {... } while(0)`` macro idiom, + ``do { ... } while (0)`` macro idiom, without a final semicolon. Example:: - #define ADD_INT_MACRO(MOD, INT) do { \ + #define ADD_INT_MACRO(MOD, INT) \ + do { \ if (PyModule_AddIntConstant((MOD), (#INT), (INT)) < 0) { \ goto error; \ } \ From ed5ee6d665490da257e26d63aeaf164acc863cc8 Mon Sep 17 00:00:00 2001 From: "Erlend E. Aasland" Date: Wed, 1 Nov 2023 14:46:10 +0100 Subject: [PATCH 7/9] Address Victor's review regarding indent level --- peps/pep-0007.rst | 12 ++++++------ 1 file changed, 6 insertions(+), 6 deletions(-) diff --git a/peps/pep-0007.rst b/peps/pep-0007.rst index 2becf29fc0b..c06f3eb7a91 100644 --- a/peps/pep-0007.rst +++ b/peps/pep-0007.rst @@ -142,12 +142,12 @@ Code lay-out without a final semicolon. Example:: - #define ADD_INT_MACRO(MOD, INT) \ - do { \ - if (PyModule_AddIntConstant((MOD), (#INT), (INT)) < 0) { \ - goto error; \ - } \ - } while (0) + #define ADD_INT_MACRO(MOD, INT) \ + do { \ + if (PyModule_AddIntConstant((MOD), (#INT), (INT)) < 0) { \ + goto error; \ + } \ + } while (0) * ``#undef`` private macros after use. From f625e8bf42342425a860d24b6990b73efc7c3866 Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Wed, 15 Nov 2023 13:54:32 -0800 Subject: [PATCH 8/9] Update peps/pep-0007.rst Co-authored-by: Erlend E. Aasland --- peps/pep-0007.rst | 2 +- 1 file changed, 1 insertion(+), 1 deletion(-) diff --git a/peps/pep-0007.rst b/peps/pep-0007.rst index c06f3eb7a91..bb09a137db1 100644 --- a/peps/pep-0007.rst +++ b/peps/pep-0007.rst @@ -149,7 +149,7 @@ Code lay-out } \ } while (0) -* ``#undef`` private macros after use. +* ``#undef`` file local macros after use. * Put blank lines around functions, structure definitions, and major sections inside functions. From 6dc7d4de60d7d438e2e2981c6fb0c817893acfce Mon Sep 17 00:00:00 2001 From: Barry Warsaw Date: Wed, 15 Nov 2023 13:55:04 -0800 Subject: [PATCH 9/9] Update peps/pep-0007.rst Co-authored-by: Erlend E. Aasland --- peps/pep-0007.rst | 3 +++ 1 file changed, 3 insertions(+) diff --git a/peps/pep-0007.rst b/peps/pep-0007.rst index bb09a137db1..fc86f045067 100644 --- a/peps/pep-0007.rst +++ b/peps/pep-0007.rst @@ -149,6 +149,9 @@ Code lay-out } \ } while (0) + // To be used like a statement with a semicolon: + ADD_INT_MACRO(m, SOME_CONSTANT); + * ``#undef`` file local macros after use. * Put blank lines around functions, structure definitions, and major