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

On Wed, Aug 9, 2017 at 7:03 AM, Ævar Arnfjörð Bjarmason
[off-list ref] wrote:

On Wed, Aug 09 2017, Jeff King jotted:

quoted

On Mon, Aug 07, 2017 at 06:25:54PM -0700, Brandon Williams wrote:

quoted

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.

quoted

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)

quoted

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).