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."
_______________________________________________
LibreOffice mailing list
[email protected]
https://lists.freedesktop.org/mailman/listinfo/libreoffice
