Re: [RFC] clang-format: outline the git project's coding style

[Stefan Beller <sbeller@google.com>]

On Wed, Aug 9, 2017 at 7:03 AM, Ævar Arnfjörð Bjarmason
<avarab@gmail.com> wrote:
>
> On Wed, Aug 09 2017, Jeff King jotted:
>
>> On Mon, Aug 07, 2017 at 06:25:54PM -0700, Brandon Williams wrote:
>>
>>> I'm sure this sort of thing comes up every so often on the list but back at
>>> git-merge I mentioned how it would be nice to not have to worry about style
>>> when reviewing patches as that is something mechanical and best left to a
>>> machine (for the most part).  I saw that 'clang-format' was brought up on the
>>> list once before a couple years ago
>>> (https://public-inbox.org/git/20150121220903.GA10267@peff.net/) but nothing
>>> really came of it.  I spent a little bit of time combing through the various
>>> options and came up with this config based on the general style of our code
>>> base.  The big issue though is that our code base isn't consistent so try as
>>> you might you wont be able to come up with a config which matches everything we
>>> do (mostly due to the inconsistencies in our code base).
>>
>> Right, the reason I stopped pursuing it was that I couldn't find a way
>> to have it make suggestions for new code without nagging about existing
>> code. If we were to aggressively reformat to match the tool for existing
>> code, that would help. But I'm a bit worried that there would always be
>> suggestions from the tool that we don't agree with (i.e., where the
>> guiding principle is "do what is readable").

We may have different opinions on what is readable/beautiful code.
If we were to follow a mutual agreed style that is produced by a tool,
we could use clean/smudge filters with different settings each.

But I think we'd rather want to find the closest approximation to our
current style first.

>> I dunno. I guess "go fmt" people decided to just treat the tool's output
>> as the One True Way. I haven't written enough Go to have an opinion
>> myself, but it seems to at least work for them.
>
> (I have no opinion either way on whether this clang formatting this is a
> good idea or not)

I think it is actually beneficial as it is one less thing to worry about
as a contributor.  Maybe compare it to programming language that
has garbage collection built in, which is also a feature to allow the
contributor to focus on "what is important". (style is not, all it can do
is hold back progress by too much nitpicking IMHO)

>> What does the tooling look like these days for just adjusting lines
>> touched by a given patch?

$ clang-format --help

USAGE: clang-format [options] [<file> ...]
..
  -i                        - Inplace edit <file>s, if specified..
  -lines=<string>           - <start line>:<end line> - format a range of
                              lines (both 1-based).
                              Multiple ranges can be formatted by specifying
                              several -lines arguments.
                              Can't be used with -offset and -length.
                              Can only be used with one input file.
..

I would think based on these options, a pre commit hook can be
written that formats precisely the touched lines of code of each file.

>
> Presumably even if it sucked we could easily write a "./git-fmt-check.sh
> <file>" script to do it which would do the following:
>
>  1. Check out the master branch
>  2. Apply code formatting to entire project (or just the files you
>     changed)
>  3. Commit that on a throwaway branch
>  4. Switch back to your WIP branch
>  5. See if it would merge cleanly with the throwaway code formatting
>     branch (I forget the actual 'not a real merge but check' command to
>     do this, but it exists).
>
> If there were any reported conflicts presumably the new code you're
> adding is violating the coding standards laid out in this file. If not
> you're good.

This approach certainly works, but it *adds* one more step to what
a contributor may need to do before sending a patch. I think the intention
with a codified style is to *remove* a step (as a machine will do it for you).