[Lldb-commits] [lldb] r223543 - First pass at a description of the lldb coding conventions.

Jim Ingham jingham at apple.com
Fri Dec 5 15:18:01 PST 2014

Author: jingham
Date: Fri Dec  5 17:18:01 2014
New Revision: 223543

URL: http://llvm.org/viewvc/llvm-project?rev=223543&view=rev
First pass at a description of the lldb coding conventions.


Added: lldb/trunk/www/lldb-coding-conventions.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/lldb-coding-conventions.html?rev=223543&view=auto
--- lldb/trunk/www/lldb-coding-conventions.html (added)
+++ lldb/trunk/www/lldb-coding-conventions.html Fri Dec  5 17:18:01 2014
@@ -0,0 +1,135 @@
+<!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">
+<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>
+    <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">Getting Started</h1>
+				<div class="postcontent">
+                                  <p>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.
+                                      <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, 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.
+                                      <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.
+                                      <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.
+                                      <p>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.
+                                        <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>

Modified: lldb/trunk/www/sidebar.incl
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/sidebar.incl?rev=223543&r1=223542&r2=223543&view=diff
--- lldb/trunk/www/sidebar.incl (original)
+++ lldb/trunk/www/sidebar.incl Fri Dec  5 17:18:01 2014
@@ -45,6 +45,7 @@
       <li><a href="/cpp_reference/html/index.html">C++ API Documentation</a></li>
       <li><a href="/source.html">Source</a></li>
       <li><a href="/build.html">Build</a></li>
+      <li><a href="/lldb-coding-conventions.html">Coding Conventions</a></li>      
       <li><a href="http://llvm.org/bugs">Bug Reports</a></li>
       <li><a href="http://llvm.org/svn/llvm-project/lldb/trunk">Browse SVN</a></li>
       <li><a href="http://llvm.org/viewvc/llvm-project/lldb/trunk">Browse ViewVC</a></li>

More information about the lldb-commits mailing list