[lldb-dev] LLDB Coding Style

[jingham at apple.com]

> On Aug 19, 2014, at 10:37 AM, Enrico Granata <egranata at apple.com> wrote:
> 
> This is my take on a couple of these - most likely the combination of how the convention was explained to me when I started work on LLDB, and then a few years of me adjusting to it, with varied success.
> To be taken with a grain of salt, or two.
> 
>> On Aug 19, 2014, at 10:16 AM, Zachary Turner <zturner at google.com> wrote:
>> 
>> I brought this up in a thread on lldb-commits, but since it is of more general interest, I want to make a thread here as well.
>> 
>> Can we have clear direction on LLDB coding style?  Ideally in the form of an update to lldb.llvm.org, but as that might require a little more effort, even some details in a response to this thread would be a help.  Some things I've deduced from looking at the code, and other things I'm not so sure about, because of inconsistencies in the code or just no clear rule.
>> 
>> Indentation width: 4
>> Column limit: 140  (does this apply to comments too?  Most function-declaration comments seem to wrap at 80)
> 
> I don’t think there is an explicit column limit. That’s not to be taken as 300 columns being OK, but we are also not as strict as the rest of LLVM on a specific number.
> I tend to wrap my function declarations when they have a lot of arguments, not so much for column limits, but for readability.
> I also have a penchant for grouping options in option classes, but that’s just my personal taste, not a guideline.
> 
>> Brace style: Allman
>>     if (foo)
>>     {
>>         // code here
>>     }
>> 
> 
> I sometimes get away with
> if (foo)
> 	oneLineHere();
> 
> but yes, braces on separate line - and I believe there actually is a preference for erring on the side of having braces even in the one statement case.

Mail probably put in extra spaces in Enrico's reply, should be 4 spaces.  If you are going to use curly's, they are "Allman".  If you want to do a two liner like this, that's fine, but generally put a blank line after for readability.  I don't think we have a prejudice against this, but I try not to do:

if ()
{
    // Something
}
else
   // Something

Because the groupings get harder to parse.


> 
>> Break after function return type: Always, only on declarations, only on definitions, only in headers, or never?
>> 

Always in definitions.  There are some header files that don't do this for the declaration, for instance the Thread Plan subclasses where you have to override a bunch of methods to implement the class but the methods you are implementing are boiler plate so taking up a lot of visual space for them isn't useful.  But we feel the need for a hard and fast rule I would go with always.


>> Space before function parentheses: When?
> 
> I do both always. Or rather, the first I do always.
> The second, I tend to do it at declarations/definitions - a little less religiously at call sites
> As a post-hoc rationalization, that makes it easier to look for function definitions vs usages, i.e. look for ‘Foo (‘ if you want to see where Foo is defined, for ‘Foo(‘ to see where Foo is used
> In practice, I think there is enough variety in this regard that this will fail more often than it works
> 

I generally do space after unless you are chaining function calls, so:

    x = foo (arguments);

because it helps my eyes parse the function name more easily.  But

    x = foo->GetSomething()->GetSomethingElse().CallIt(arguments)

because the spaces in that case break up the flow.

>> 
>> Indent case labels inside switch: A or B below?
>>     switch (foo)
>>     {
>>         case A:
>>     case B:
>>     }
>> 
>> Indent braces inside of a case: A or B below?
>>     switch (foo)
>>     {
>>         case A:
>>         {
>>         }
>>         case B:
>>             {
>>             }
>>     }
>> 

We don't seem to be very consistent about this.  When we started off we were going to always line up the "case" with the curly for the switch, but our usage seems to vary.

>> Any other rules I should be cognizant of?
> 
> Well, the obvious; member variables start with an m_, globals with g_, class and function names start with uppercase letters, and then go SomewhatLikeThisYouSee, member variables go instead m_likeThisForVariables.

We also indicate the the "owning" variables - shared pointer, unique pointer and the like with _sp, _up and though we don't use them much anymore _ap.  

And locals should be foo_bar_baz, always lower case.

You will see some places where Sean has to plug into the LLVM code more directly where he'll start coding like LLVM.  I think that's a little weird, but it makes sense to him so I'm okay with that.

Jim