Subject: Automatic code formatting

From: "brian m. carlson" <[email-masked]>
Date: Sun, 10 Jul 2022 21:50:15 +0000

In the past, we've discussed the possibility of using an automatic code
formatter for Git.  That discussion has, as we've seen, not led to us
using one.  I'd like to reopen the discussion and provide a couple
reasons why I think it's a good idea.

We've spent a lot of work encouraging newcomers to contribute to Git.
It's demoralizing when your code comes back with many code style nits to
fix, and it leads to a barrier to contribution.  I also find that I am
likely to take longer to reroll a series if there are many nits to be
fixed, and I find that code style comments are a frequent discussion
topic on my series (even though I generally try to be cognizant of
them).

Having a code formatting tool means that the work for a contributor to
format the file properly consists of about two keystrokes.  This
substantially reduces the amount of time that contributors must spend
thinking about code formatting and simplifies it to an automatic process
that, if we choose, can even be verified in CI.

Most projects written in languages like Rust or Go use an automatic
formatter.  In Go's case, the formatter is specifically stated to be a
fixed style that is nobody's favourite, but because there's an automatic
formatter, everybody just uses it.  Personally, I don't love our coding
style now (I'm a 4-space person in C), but I would love it a lot more if
I didn't have to think about it.  I am substantially less picky about
what the style is than that we have an automated tool to tidy our code,
and I'm okay with us producing the occasional slightly suboptimal style
for the improved efficiency we get.

The impetus for me bringing this up is that I'm rebasing the
SHA-1/SHA-256 interop work to continue work on it and I find myself
spending a lot of time cleaning up formatting that I could instead be
spending on debugging why my tests are failing or writing new code.  I
would like to spend less time on boring scut work and more time solving
interesting problems, as I'm sure we all would.

I should point out that most platforms (and all major platforms) have
clang and therefore I think clang-format should be a fine choice.  It's
highly configurable and will let us pick a style that most resembles the
one we have now. However, I'm not picky and if we like something else
better, great.  As long as the option we pick is shipped in Debian, I'm
for it.

I should note that we already have a .clang-format file, so we can
already use clang-format.  However, we cannot blindly apply it because
it produces output that is not always conformant with our style.  My
proposal here is to define our style in terms of the formatter to avoid
this problem.

Hopefully we can move forward with this discussion and come to some
productive resolution.
-- 
brian m. carlson (he/him or they/them)
Toronto, Ontario, CA