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

[Zachary Turner]

one thing I forgot to add.  The reason I'm bringing this up now is because
I've seen more activity in LLDB over the past 2 months or so.  Off the top
of my head, we have people actively supporting Linux, Android, FreeBSD,
Apple, Hexagon, multiple platforms with lldb-mi.  I've also started to see
more participation from people who started out on the LLVM side of things.

So I think it's worth reconsidering the benefit of a specific set of rules
vs. how "welcoming" our code is to people from the LLVM side of things.
One area where LLDB currently is lacking is with regards to LLVM
expertise.  Most people are focused on details of a specific platform's
debugging experience, and I think the benefit to LLDB would be very large
if we had more people from the LLVM side hacking on things.

On Mon Feb 09 2015 at 10:53:31 AM Zachary Turner <zturner at google.com> wrote:

> 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/fe4ef1b0/attachment.html>