[lldb-dev] Style guide and clang-format.

[Zachary Turner]

A while back I asked about the possibility of bringing our style guide
closer to LLVM's.  To that end, I made a clang-format configuration file
for LLDB and included it at the base of LLDB's repo.  At the time I didn't
know this, and I had my own hacked up solution, but it turns out it's very
easy to use clang-format to format only those lines in a CL that have
changed.  Here's how you do it.  Steps 1-3 only need to happen once, and
after that you only need 1 command to invoke clang-format.

1) Build clang-format.  This is very easy to do, since everyone building
LLDB already has clang checked out.  So all you need to do is point CMake
to the root of your llvm source tree like this:
src/lldb/llvm> mkdir build
src/lldb/llvm> cd build
src/lldb/llvm/build> cmake -G Ninja ..
(wait a while)

Then build clang-format
src/lldb/llvm/build> ninja clang-format

2) Copy clang-format and the git clang-format command extension to
somewhere in your path
src/lldb/llvm/build> mkdir ~/git-clang-format
src/lldb/llvm/build> cp bin/clang-format ~/git-clang-format
src/lldb/llvm/build> cp ../tools/clang/tools/clang-format/git-clang-format
~/git-clang-format
src/lldb/llvm/build> export PATH=$PATH:~/git-clang-format

3) Make sure that git-clang-format is executable
src/lldb/llvm/build> chmod +x ~/git-clang-format/git-clang-format

4) Run git clang-format!
src/lldb/llvm/build> cd ../..
src/lldb> git clang-format

This will run clang-format against the files you have staged.  It will only
reformat lines which are part of the diff, so you don't have to worry about
a lot of pollution.

It would be great if more people started using this.  It makes it so you
don't have to think about formatting as you type.  There are a very few
cases where it gets things wrong, so be careful.  lldb-forward.h is a good
example of this.  When you have types that are aligned or justified it will
remove the alignment.  That's about the only limitation though.

There is 1 section I can think of where the clang-format specification file
differs from LLDB's documented
<http://lldb.llvm.org/lldb-coding-conventions.html> coding convention (BTW,
thanks Jim for getting this up).  I would like to propose removing this
line from LLDB's style guide.  It is this part:

Another place where lldb and llvm differ is in whether to put a space
between a function name, and the parenthesis that begins its argument list.
In lldb, we insert a space between the name and the parenthesis, except for
functions that take no parameters, or when the function is in a chain of
functions calls. However, this rule has been applied rather haphazardly in
lldb at present.

The clang-format file simply does not put a space there.  I think it is
worth removing this line from the style guide for a couple reasons:

1) It differs from LLVM (actually I want to remove even more lines from the
style guide for this reason, but for now I only want to ruffle a few
feathers, not all the feathers :)
2) clang-format does not have a way to specify rules with exceptions that
are this detailed.
3) It is not consistently applied in the codebase as is.
4) The rule is confusing, and the benefit isn't clear enough to warrant
having its inclusion, especially given that the confusing nature of the
rule is probably a leading cause of #3.

To be clear: I'm not saying we ban this.  I'm saying remove it from the
style guide.  If you want to still do it, then by all means still do it.
And if you use clang-format, clang-format will remove the space for you.

Thoughts?  Suggestions?
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/lldb-dev/attachments/20150209/282a70c1/attachment.html>