Some points on clang-format usage

[Stephan Bergmann]

On 11/17/2017 10:03 AM, Stephan Bergmann wrote:
> * 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.


Another gotcha to watch out for related to comments is how

> void decl1(); // lengthy comment comment comment comment comment comment comment comment comment
>               // comment comment comment comment comment comment comment comment pertaining to decl1
> void decl2();
>     // lengthy comment comment comment comment comment comment comment comment pertaining to decl2
> void decl3();
> 
> void f() {
>     statement1(); // lengthy comment comment comment comment comment comment comment comment comment
>                   // comment comment comment comment comment comment pertaining to statement1
>     statement2();
>         // lengthy comment comment comment comment comment comment comment pertaining to statement2
>     statement3();
> }

is reformatted to

> void decl1(); // lengthy comment comment comment comment comment comment comment comment comment
>     // comment comment comment comment comment comment comment comment pertaining to decl1
> void decl2();
> // lengthy comment comment comment comment comment comment comment comment pertaining to decl2
> void decl3();
> 
> void f()
> {
>     statement1(); // lengthy comment comment comment comment comment comment comment comment comment
>         // comment comment comment comment comment comment pertaining to statement1
>     statement2();
>     // lengthy comment comment comment comment comment comment comment pertaining to statement2
>     statement3();
> }