Some points on clang-format usage

[Stephan Bergmann]

Some random points regarding our recently introduced use of clang-format:


* clang-format cannot automatically reformat code

Most comments in the code are written by humans, for humans.  They are 
often placed in a way that makes it technically unclear what code they 
pertain to, relying on humans to nevertheless easily discern that.  For 
example, in

> void f(int x) { g(x + 1); } // long comment explaining how g internally subtracts one

the comment clearly pertains to the call to g.  Yet, clang-format will 
reformat this to something like

> void f(int x)
> {
>     g(x + 1);
> } // long comment explaining how g internally subtracts one

instead of

> void f(int x)
> {
>     g(x + 1); // long comment explaining how g internally subtracts one
> }

thereby obscuring things.  Always review automatically reformatted code 
for glitches like this.


* Don't reformat when moving an existing file

When moving an old file that is listed in solenv/clang-format/blacklist 
(so doesn't automatically get reformatted upon commit), adapt 
solenv/clang-format/blacklist to contain the new name, instead of 
provoking a reformat upon commit.  Otherwise, if the reformatted code 
looks sufficiently different from the original, it's hard to impossible 
to keep track in the git history of which file was moved where.


* Keep your local .clang-format up to date

There's been changes to it, and there might be more coming (though 
that's hopefully getting less and less likely).  If you create commits 
involving new files on an old master revision, you risk wrongly 
formatted code (and thus the need for reformatting follow-up commits) 
when that commit is eventually cherry-picked into the upstream git repo. 
  "Pull early, pull often."