[v4,1/2] clang-format: re-adjust line break penalties

Commit Message

karthik nayak Oct. 18, 2024, 8:46 a.m. UTC

In 42efde4c29 (clang-format: adjust line break penalties, 2017-09-29) we
adjusted the line break penalties to really fine tune what we care about
while doing line breaks. Modify some of those to be more inline with
what we care about in the Git project now.

We need to understand that the values set to penalties in
'.clang-format' are relative to each other and do not hold any absolute
value. The penalty arguments take an 'Unsigned' value, so we have some
liberty over the values we can set.

First, in that commit, we decided, that under no circumstances do we
want to exceed 80 characters. This seems a bit too strict. We do
overshoot this limit from time to time to prioritize readability. So
let's reduce the value for 'PenaltyExcessCharacter' to 10. This means we
that we add a penalty of 10 for each character that exceeds the column
limit. By itself this is enough to restrict to column limit. Tuning
other penalties in relation to this is what is important.

The penalty `PenaltyBreakAssignment` talks about the penalty for
breaking an assignment operator on to the next line. In our project, we
are okay with this, so giving a value of 5, which is below the value for
'PenaltyExcessCharacter' ensures that in the end, even 1 character over
the column limit is not worth keeping an assignment on the same line.

Similarly set the penalty for breaking before the first call parameter
'PenaltyBreakBeforeFirstCallParameter' and the penalty for breaking
comments 'PenaltyBreakComment' and the penalty for breaking string
literals 'PenaltyBreakString' also to 5.

Finally, we really care about not breaking the return type into its own
line and we really care about not breaking before an open parenthesis.
This avoids weird formatting like:

   static const struct strbuf *
          a_really_really_large_function_name(struct strbuf resolved,
          const char *path, int flags)

or

   static const struct strbuf *a_really_really_large_function_name(
   	    struct strbuf resolved, const char *path, int flags)

to instead have something more readable like:

   static const struct strbuf *a_really_really_large_function_name(struct strbuf resolved,
                                                                   const char *path,
                                                                   int flags)

(note: the tabs here have been replaced by spaces for easier reading)

This is done by bumping the values of 'PenaltyReturnTypeOnItsOwnLine'
and 'PenaltyBreakOpenParenthesis' to 300. This is so that we can allow a
few characters above the 80 column limit to make code more readable.

Signed-off-by: Karthik Nayak <[e-mail]>
---
 .clang-format | 13 +++++++------
 1 file changed, 7 insertions(+), 6 deletions(-)

Comments

Justin Tobler Oct. 25, 2024, 2:37 a.m. UTC | #1

On 24/10/18 10:46AM, Karthik Nayak wrote:
> In 42efde4c29 (clang-format: adjust line break penalties, 2017-09-29) we
> adjusted the line break penalties to really fine tune what we care about
> while doing line breaks. Modify some of those to be more inline with
> what we care about in the Git project now.

From my understanding, the original motivation for these changes was to
cut down on the noise from the clang-format CI job. These changes seem
reasonable for that purpose, but affect the also formatter in general.

Out of curiousity, would it be possible to just configured clang-format
for the CI job to behave in this manner? Ultimately, I'm not sure that
would be good idea though because having a diverged set of rules may
just cause more noise.

-Justin

karthik nayak Oct. 25, 2024, 9:48 a.m. UTC | #2

Justin Tobler <[e-mail]> writes:

> On 24/10/18 10:46AM, Karthik Nayak wrote:
>> In 42efde4c29 (clang-format: adjust line break penalties, 2017-09-29) we
>> adjusted the line break penalties to really fine tune what we care about
>> while doing line breaks. Modify some of those to be more inline with
>> what we care about in the Git project now.
>
> From my understanding, the original motivation for these changes was to
> cut down on the noise from the clang-format CI job. These changes seem
> reasonable for that purpose, but affect the also formatter in general.
>

Yes, you're right. Which is the intended affect.

> Out of curiousity, would it be possible to just configured clang-format
> for the CI job to behave in this manner? Ultimately, I'm not sure that
> would be good idea though because having a diverged set of rules may
> just cause more noise.
>

We do that in 'ci/run-style-check.sh' already, but here I'd say there is
no need to diverge. We do want users to apply clang-format to _their_
changes, which should be similar to what the CI barfs.

Patch

diff --git a/.clang-format b/.clang-format
index 41969eca4b..66a2360ae5 100644
--- a/.clang-format
+++ b/.clang-format
@@ -209,13 +209,14 @@  KeepEmptyLinesAtTheStartOfBlocks: false
 
 # Penalties
 # This decides what order things should be done if a line is too long
-PenaltyBreakAssignment: 10
-PenaltyBreakBeforeFirstCallParameter: 30
-PenaltyBreakComment: 10
+PenaltyBreakAssignment: 5
+PenaltyBreakBeforeFirstCallParameter: 5
+PenaltyBreakComment: 5
 PenaltyBreakFirstLessLess: 0
-PenaltyBreakString: 10
-PenaltyExcessCharacter: 100
-PenaltyReturnTypeOnItsOwnLine: 60
+PenaltyBreakOpenParenthesis: 300
+PenaltyBreakString: 5
+PenaltyExcessCharacter: 10
+PenaltyReturnTypeOnItsOwnLine: 300
 
 # Don't sort #include's
 SortIncludes: false