The lldb coding conventions for the most part follow those used in llvm. For instance the importance of comments, particularly for defining classes and methods, the restrictions on features of C++ to use, and the generally excellent advice about using C++ features properly should all be followed when writing code for lldb. However, lldb does differ from the llvm coding conventions in several ways. This document outlines the most important ones.

Source code width:

lldb does not follow the 80 character line restriction llvm imposes. In our experience, trying to fit C++ code into an 80 character line results in code that is awkward to read, and the time spent trying to find good indentation points to avoid this would be much better spent on thinking about your code.

More importantly, the restriction induces coders to choose overly abbreviated names to make them better fit in 80 characters. In our opinion choosing good descriptive names is much more important than fitting in 80 characters.

In lldb, we don't have a hard character limit, though we try to keep code statements under 120 characters because it gets awkward to scan longer lines even on a fairly big monitor, and we've found at that length you seldom have to make code look ugly to get it to wrap.

However you will see some instances of longer lines. The most common occurrence is in the options tables for the CommandInterpreter, which contain the help strings as well as a bunch of important but hard to remember fields. These tables are much easier to read if all the fields line up vertically, and don't have help text interleaved in between the lines.

Indentation:

lldb uses 4 character indentation. We find this makes the code structure much easier to see when scanning code, and since we aren't trying to fit code into 80 characters, the benefit of not wasting 2 out of the 80 precious spaces per indentation level is moot.

We also use the Allman brace style rather than putting the initial brace at the end of the braced line. This makes the block structure of the code much easier to see on an initial scan, and most folks have big enough monitors nowadays that saving a few vertical lines isn't sufficiently important to outweigh this benefit.

Though the llvm coding conventions don't specify this, llvm/clang tend to declare and define methods by putting the return type and the method name on the same line. lldb puts the qualifiers and return type on a line by themselves and then the method name on the next line, i.e.: 


    virtual int
    MethodName ();

When you are scanning a header file, that makes the method names stand out more easily, though at the cost of an extra line. When you have a editor that scrolls smoothly, it's easy to move through pages so the extra line is less important than the ease of picking out the method names, which is what you generally are scanning for.

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.

Names:

lldb's naming conventions are different and slightly more restrictive than the llvm ones. The goal is to make it easy to tell from immediate context the lifespan and what kind of entity a given name represents, which makes reading code you are not familiar with much easier. lldb uses the following conventions:

  • Macro definitions when needed are in all caps, nothing else should be in all caps.
  • Types and classes are in CamelCase with an initial capital.
  • Methods are also in CamelCase with an initial capital. The initial capital for methods has the handy benefit that it gets our method names into a different namespace than the standard C/C++ library functions, which tend to all be lower-cased. There are also places in lldb where we wrap clang objects in classes appropriate to lldb, and the difference from the llvm convention here actually makes it easier to tell whether you are using the clang object directly or are going through the lldb wrapper.
  • All variables are written in lower case, with "_" as the word separator. We find that using a different capitalization and word separation convention makes variables and methods/types immediately visually distinct, resulting in code which is much easier to read.
  • class ivars all start with "m_". It is important to be able to tell ivars from local variables, and this makes the distinction easily apparent. Some other coding conventions use an initial "_", but this seems much harder to spot. Also it allows:
  • Class statics and other global variables start with "g_". You should be suspicious of all global variables, so having them stand out lexically is a good thing.
  • We also use the suffixes "_sp" and "_up" for shared and unique pointer variables. Since these have very different lifecycle behaviors it is worthwhile to call them out specially. You will see some "_ap" suffixes around. There should be no auto_ptr variables left in lldb, but when we converted to unique_ptr's not all the names were changed. Feel free to change these to "_up" when you touch them for some other reason.
  • enumerations that might end up being in the lldb SB API's should all be written like: 
    
    typedef enum EnumName
    {
        eEnumNameFirstValue,
        eEnumNameSecondValue,
    } EnumName;

    This redundancy is important because the enumerations that find their way through SWIG into Python will show up as lldb.eEnumNameFirstValue, so including the enum name in the value name disambiguates them in Python.

    Since we've started allowing C++11 in lldb, we have started using "enum class" instead of straight enums. That is fine for enums that will only ever exist on the lldb_private side of lldb, but err on the side of caution here on't do that for any enums that might find their way into the SB API's, since then you will have to change them so we can get them through SWIG.

    • Also, on a more general note, except when you are using a temporary whose lifespan is not far past its definition, never use one or two character names for ivars. Always use something descriptive, and as far as possible use the same name for the same kind of thing (or the name with an appropriate prefix.) That way if I'm looking at one use of a type, I can search on the variable name and see most of the other uses of the same type of thing. That makes it much easier to get quickly up to speed on how that type should be used.