Re: [PATCH] clang-format: add configuration file

[Miguel Ojeda]

On Tue, Mar 13, 2018 at 10:00 PM, Andrew Morton
<akpm@xxxxxxxxxxxxxxxxxxxx> wrote:
> On Tue, 13 Mar 2018 00:39:52 +0100 Miguel Ojeda <miguel.ojeda.sandonis@xxxxxxxxx> wrote:
>
>> --- a/Documentation/process/4.Coding.rst
>> +++ b/Documentation/process/4.Coding.rst
>> @@ -58,6 +58,12 @@ can never be transgressed.  If there is a good reason to go against the
>>  style (a line which becomes far less readable if split to fit within the
>>  80-column limit, for example), just do it.
>>
>> +Note that you can use the clang-format tool to help you with these rules
>> +and to quickly re-format parts of your code automatically. It is specially
>> +useful for new files/code and to spot coding style mistakes. It is also
>> +useful to sort #includes, to align variables or comments, to reflow text
>> +and other similar tasks.
>
> It would be rather helpful to tell people how to invoke clang-format.
> Is it just "clang-format foo.c" or what?
>

Indeed! I will add more information. Here is some more we can put (I
will properly rewrite it, but you can see it as a draft and as the
answer to your question! :-)

You can call "clang-format foo.c" and it will output to the standard
output the formatted file (using the configuration file automatically
if it is any of the parents, a la git). The -i does the replacements
inline. However, for the kernel, it is best to use it with one of the
editor integrations: the issue is that clang-format does not format
everything perfectly as we want for the kernel [*], so it is best used
to either 1) format portions of files or 2) check patches.

  - For formatting portions of files, you just select inside your text
editor something and press your favorite key binding to re-format it
(clang-format has some parameters that the editor passes when invoking
it). Since it is very fast, it works very well. Integrations with vim
and emacs come with the tool; for most other popular editors, you can
usually find a plugin or similar in the manager of such editor.

  - For checking patches, since it comes with support to read unified
diffs, it is very easy to use it for patches and for commits. What you
will see is both things that could be improved because there was a
typo/mistake by the patch author, and things that you should ignore
because clang-format does not format those cases -- it is very easy to
know which are which if you use the tool a few times, specially if you
are looking at the difference with git diff.

When I was testing clang-format to come with the configuration, I was
running the tool against full files, and while there were many cases
that have to be ignored, like [*], it is also very easy to see some
mistakes in the code. If it gets popular, I am sure people will come
up with ready-to-be-used scripts/hooks and things like that, but for
the moment I thought the best was to at least have the basic
configuration in and iterate from there. At least there is *one*
person (what an audience! :-) using it currently, since if you grep
for "clang-format" you will see one staging driver with one comment in
the code to turn off the formatting in a block. I also thought that
the sooner we define how we will use it (e.g. whether we allow those
"don't-format-this" marks, the name for those marks -- it is
configurable, etc.), the best.

[*] For instance, it does not support alignment of one-line #defines
-- but it aligns multiline #defines quite well, though. So you won't
run it for full files typically, but for groups of things. Another
simple case where it is best for selections and not for full files (at
least existing files) is the sorting of #includes i.e. It is great if
you use it when selecting a bunch of them that you know will look
better if sorted, but probably you don't want to sort ALL of them
(even if it respects the grouping, which it does); expect if you are
writing a new file.

Cheers,
Miguel