| <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd"> |
| <html xmlns="http://www.w3.org/1999/xhtml"> |
| <head> |
| <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" /> |
| <link href="style.css" rel="stylesheet" type="text/css" /> |
| <title>LLDB Tutorial</title> |
| </head> |
| |
| <body> |
| <div class="www_title"> |
| The <strong>LLDB</strong> Coding Conventions |
| </div> |
| |
| <div id="container"> |
| <div id="content"> |
| <!--#include virtual="sidebar.incl"--> |
| <div id="middle"> |
| <div class="post"> |
| <h1 class ="postheader">LLDB Coding Conventions</h1> |
| <div class="postcontent"> |
| |
| |
| <p>The LLDB coding conventions differ in a few important respects from LLVM.</p> |
| |
| <p> |
| Note that <a href="http://clang.llvm.org/docs/ClangFormat.html">clang-format</a> 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. |
| </p> |
| <p> |
| <b>Important</b>: Where not explicitly outlined below, assume that the |
| <a href="http://llvm.org/docs/CodingStandards.html">LLVM Coding Conventions</a> are to be followed. |
| </p> |
| |
| <h3>Source code width:</h3> |
| <p>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. |
| |
| <p>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. |
| |
| <p>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. |
| |
| <p>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. |
| |
| <h3>Indentation:</h3> |
| <p>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. |
| |
| <p>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. |
| |
| <p>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.: |
| <code><pre><tt> |
| virtual int |
| MethodName (); |
| </code></pre></tt> |
| <p>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. |
| |
| <h3> Names:</h3> |
| <p>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: |
| |
| <ul> |
| <li> Macro definitions when needed are in all caps, nothing else should be in all caps. </li> |
| <li>Types and classes are in CamelCase with an initial capital.</li> |
| <li>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.</li> |
| <li> 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.</li> |
| <li> 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:</li> |
| <li> 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.</li> |
| <li>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.</li> |
| <li> enumerations that might end up being in the lldb SB API's should all be written like: |
| |
| <pre><code><tt> |
| typedef enum EnumName |
| { |
| eEnumNameFirstValue, |
| eEnumNameSecondValue, |
| } EnumName; |
| </pre></code></tt> |
| |
| <p>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. |
| |
| <p>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.</li> |
| |
| <p> 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. |
| </li> |
| |
| </div> |
| </body> |
| </html> |
