www/lldb-coding-conventions.html

   1 <!DOCTYPE html PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN" "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
   2 <html xmlns="http://www.w3.org/1999/xhtml">
   3 <head>
   4 <meta http-equiv="Content-Type" content="text/html; charset=iso-8859-1" />
   5 <link href="style.css" rel="stylesheet" type="text/css" />
   6 <title>LLDB Tutorial</title>
   7 </head>
   8
   9 <body>
  10     <div class="www_title">
  11       The <strong>LLDB</strong> Coding Conventions
  12     </div>
  13
  14 <div id="container">
  15         <div id="content">
  16          <!--#include virtual="sidebar.incl"-->
  17                 <div id="middle">
  18                         <div class="post">
  19                                 <h1 class ="postheader">LLDB Coding Conventions</h1>
  20                                 <div class="postcontent">
  21
  22
  23                                   <p>The LLDB coding conventions differ in a few important respects from LLVM.</p>
  24
  25                                   <p>
  26                                     Note that <a href="http://clang.llvm.org/docs/ClangFormat.html">clang-format</a> will deal with
  27                                     most of this for you, as such is suggested to run on patches before uploading.  Note however that
  28                                     clang-format is not smart enough to detect instances of humans intentionally trying to line variables
  29                                     up on a particular column boundary, and it will reformat them to remove this "extraneous" whitespace.
  30                                     While this is usually the correct behavior, LLDB does have many uses of manually aligned types and
  31                                     fields, so please be aware of this behavior of clang-format when editing this type of code.
  32                                   </p>
  33                                   <p>
  34                                     <b>Important</b>: Where not explicitly outlined below, assume that the
  35                                     <a href="http://llvm.org/docs/CodingStandards.html">LLVM Coding Conventions</a> are to be followed.
  36                                   </p>
  37
  38                                       <h3>Source code width:</h3>
  39                                       <p>lldb does not follow the 80 character line restriction llvm imposes.  In our
  40                                         experience, trying to fit C++ code into an 80 character line results in code that
  41                                         is awkward to read, and the time spent trying to find good indentation points to
  42                                         avoid this would be much better spent on thinking about your code.
  43
  44                                       <p>More importantly, the restriction induces coders to choose overly abbreviated names
  45                                         to make them better fit in 80 characters.  In our opinion choosing good descriptive
  46                                         names is much more important than fitting in 80 characters.
  47
  48                                       <p>In lldb the limit for code lines is 120 characters because it gets awkward to scan
  49                                          longer lines even on a fairly big monitor, and we've found at that length you seldom
  50                                          have to make code look ugly to get it to wrap.
  51
  52                                       <p>However you will see some instances of longer lines. The most common occurrence is in
  53                                         the options tables for the CommandInterpreter, which contain the help strings as well as
  54                                         a bunch of important but hard to remember fields.  These tables are much easier to read if
  55                                         all the fields line up vertically, and don't have help text interleaved in between the lines.
  56                                         This is another thing to keep in mind when running clang-format, as it will always wrap at
  57                                         120, so you will need to tweak its output when running against intentionally too-long lines.
  58
  59                                       <h3>Indentation:</h3>
  60                                       <p>lldb uses 4 character indentation.  We find this makes the code structure much easier to
  61                                         see when scanning code, and since we aren't trying to fit code into 80 characters, the
  62                                         benefit of not wasting 2 out of the 80 precious spaces per indentation level is moot.
  63
  64                                       <p>We also use the Allman brace style rather than putting the initial brace at the end
  65                                         of the braced line.  This makes the block structure of the code much easier to see on
  66                                         an initial scan, and most folks have big enough monitors nowadays that saving a few
  67                                         vertical lines isn't sufficiently important to outweigh this benefit.
  68
  69                                       <p>Though the llvm coding conventions don't specify this, llvm/clang tend to declare and
  70                                         define methods by putting the return type and the method name on the same line.  lldb
  71                                         puts the qualifiers and return type on a line by themselves and then the method name on
  72                                         the next line, i.e.:
  73                                         <code><pre><tt>
  74     virtual int
  75     MethodName ();
  76                                         </code></pre></tt>
  77                                       <p>When you are scanning a header file, that makes the method names stand out more easily,
  78                                         though at the cost of an extra line.  When you have a editor that scrolls smoothly, it's
  79                                         easy to move through pages so the extra line is less important than the ease of picking
  80                                         out the method names, which is what you generally are scanning for.
  81
  82                                         <h3> Names:</h3>
  83                                           <p>lldb's naming conventions are different and slightly more restrictive than the llvm
  84                                             ones.  The goal is to make it easy to tell from immediate context the lifespan
  85                                             and what kind of entity a given name represents, which makes reading code you are not familiar
  86                                             with much easier.  lldb uses the following conventions:
  87
  88                                             <ul>
  89                                               <li> Macro definitions when needed are in all caps, nothing else should be in all caps. </li>
  90                                               <li>Types and classes are in CamelCase with an initial capital.</li>
  91                                               <li>Methods are also in CamelCase with an initial capital.  The initial capital for methods
  92                                                 has the handy benefit that it gets our method names into a different namespace
  93                                                 than the standard C/C++ library functions, which tend to all be lower-cased.
  94                                                 There are also places in lldb where we wrap clang objects in classes appropriate to lldb,
  95                                                 and the difference from the llvm convention here actually  makes it easier to tell
  96                                                 whether you are using the clang object directly or are going through the lldb wrapper.</li>
  97                                               <li> All variables are written in lower case, with "_" as the word separator.  We find that
  98                                                 using a different capitalization and word separation convention makes variables and methods/types
  99                                                 immediately visually distinct, resulting in code which is much easier to read.</li>
 100                                               <li> class ivars all start with "m_".  It is important to be able to tell ivars from local
 101                                                 variables, and this makes the distinction easily apparent.  Some other coding conventions
 102                                                 use an initial "_", but this seems much harder to spot.  Also it allows:</li>
 103                                               <li> Class statics and other global variables start with "g_".  You should be suspicious of all
 104                                                 global variables, so having them stand out lexically is a good thing.</li>
 105                                               <li>We also use the suffixes "_sp" and "_up" for shared and unique pointer variables.  Since
 106                                                 these have very different lifecycle behaviors it is worthwhile to call them out
 107                                                 specially.  You will see some "_ap" suffixes around.  There should be no auto_ptr variables
 108                                                 left in lldb, but when we converted to unique_ptr's not all the names were changed.
 109                                                 Feel free to change these to "_up" when you touch them for some other reason.</li>
 110                                               <li> enumerations that might end up being in the lldb SB API's should all be written like:
 111
 112                                                 <pre><code><tt>
 113     typedef enum EnumName
 114     {
 115         eEnumNameFirstValue,
 116         eEnumNameSecondValue,
 117     } EnumName;
 118                                                 </pre></code></tt>
 119
 120                                                 <p>This redundancy is important because the enumerations that find their way through SWIG into
 121                                                   Python will show up as lldb.eEnumNameFirstValue, so including the enum name
 122                                                   in the value name disambiguates them in Python.
 123
 124                                                 <p>Since we've started allowing C++11 in lldb, we have started using "enum class" instead of straight
 125                                                   enums.  That is fine for enums that will only ever exist on the lldb_private side of lldb, but err on
 126                                                   the side of caution here on't do that for any enums that might find their way into the SB API's, since then
 127                                                   you will have to change them so we can get them through SWIG.</li>
 128
 129                                               <p> Also, on a more general note, except when you are using a temporary whose lifespan is not
 130                                                 far past its definition, never use one or two character names for ivars.  Always use something
 131                                                 descriptive, and as far as possible use the same name for the same kind of thing (or the name
 132                                                 with an appropriate prefix.)  That way if I'm looking at one use of a type, I can search on the
 133                                                 variable name and see most of the other uses of the same type of thing.  That makes it much easier
 134                                                 to get quickly up to speed on how that type should be used.
 135                                       </li>
 136
 137 </div>
 138 </body>
 139 </html>