diff options
| author | Jim Ingham <jingham@apple.com> | 2014-12-05 23:18:01 +0000 |
|---|---|---|
| committer | Jim Ingham <jingham@apple.com> | 2014-12-05 23:18:01 +0000 |
| commit | 15fe29346089d08dd3ee6670688eb731fe3ecd97 (patch) | |
| tree | dbb485830fdbfc27abe783c62bd71d42cddf87d4 /lldb/www/lldb-coding-conventions.html | |
| parent | 89bc4850856e8ccd2ba867f02c7b005bcc22f43f (diff) | |
| download | bcm5719-llvm-15fe29346089d08dd3ee6670688eb731fe3ecd97.tar.gz bcm5719-llvm-15fe29346089d08dd3ee6670688eb731fe3ecd97.zip | |
First pass at a description of the lldb coding conventions.
llvm-svn: 223543
Diffstat (limited to 'lldb/www/lldb-coding-conventions.html')
| -rw-r--r-- | lldb/www/lldb-coding-conventions.html | 135 |
1 files changed, 135 insertions, 0 deletions
diff --git a/lldb/www/lldb-coding-conventions.html b/lldb/www/lldb-coding-conventions.html new file mode 100644 index 00000000000..9b9c8626afc --- /dev/null +++ b/lldb/www/lldb-coding-conventions.html @@ -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"> +<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">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> + +</div> +</body> +</html> |
