[PATCH] Documentation: note styling for bit fields

From: Karthik Nayak <karthik.188@gmail.com>
Date: Aug 26, 2025, 12:19 UTC
Message-ID: <20250826121928.22317-1-karthik.188@gmail.com>
In-Reply-To: <xmqqwm6uvruu.fsf@gitster.g>

Our codebase uses a lot of bit field variables, generally to mark boolean type variables. While there is a formatting rule in the '.clang-format', there is no guideline specified in the 'CodingGuidelines'.

Since the '.clang-format' is not yet enforced, let's also add a guideline with the same rule as mentioned in the '.clang-format', which is to not use any spaces around the colon, like so:

    unsigned my_field:1;
    unsigned other_field:1;
    unsigned field_with_longer_name:1;

This would allow us not to modify the clang-format file, and more importantly, discourage people from doing ugly alignment with spaces, i.e.

    unsigned my_field               : 1;
    unsigned            other_field : 1;
    unsigned field_with_longer_name : 1;

Helped-by: Junio C Hamano <gitster@pobox.com>
Signed-off-by: Karthik Nayak <karthik.188@gmail.com>
---

I think it would be worthwhile to also add this decision to the 'CodingGuidelines', but if you feel it is unnecessary, feel free to drop it.

 Documentation/CodingGuidelines | 6 ++++++
 1 file changed, 6 insertions(+)

diff --git a/Documentation/CodingGuidelines b/Documentation/CodingGuidelines
index 224f0978a8..df72fe0177 100644
--- a/Documentation/CodingGuidelines
+++ b/Documentation/CodingGuidelines
@@ -650,6 +650,12 @@ For C programs:
    cases. However, it is recommended to find a more descriptive name wherever
    possible to improve the readability and maintainability of the code.
 
+ - Bit fields should be defined without a space around the colon. E.g.
+
+   unsigned my_field:1;
+   unsigned other_field:1;
+   unsigned field_with_longer_name:1;
+
 For Perl programs:
 
  - Most of the C guidelines above apply.

-- 
2.50.1