Re: Some points on clang-format usage

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();
> }