- - -

The LLDB coding conventions differ in a few important respects from LLVM.

- -

- Note that clang-format will deal with - most of this for you, as such is suggested to run on patches before uploading. Note however that - clang-format is not smart enough to detect instances of humans intentionally trying to line variables - up on a particular column boundary, and it will reformat them to remove this "extraneous" whitespace. - While this is usually the correct behavior, LLDB does have many uses of manually aligned types and - fields, so please be aware of this behavior of clang-format when editing this type of code. -

-

- Important: Where not explicitly outlined below, assume that the - LLVM Coding Conventions are to be followed. -

-

Include Order:

-

LLDB follows LLVM's include order, - with an addition for LLDB specific headers.

-
    - -
  1. Main Module Header
    2. -
  2. Local/Private Headers
    3. -
  3. lldb/...
    4. -
  4. llvm/...
    5. -
  5. System #includes
    6. -
-

If you encounter existing code that does not follow this ordering, it should not be - taken as an indication that it is ok to not use it. Instead, the surrounding ordering - should be fixed gradually and incrementally.

-

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 the limit for code lines is 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. - This is another thing to keep in mind when running clang-format, as it will always wrap at - 120, so you will need to tweak its output when running against intentionally too-long 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. - -

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. - - -