[Lldb-commits] [lldb] r280892 - Remove lldb coding conventions as they are no longer relevant.
Jim Ingham via lldb-commits
lldb-commits at lists.llvm.org
Wed Sep 7 17:42:02 PDT 2016
Author: jingham
Date: Wed Sep 7 19:42:02 2016
New Revision: 280892
URL: http://llvm.org/viewvc/llvm-project?rev=280892&view=rev
Log:
Remove lldb coding conventions as they are no longer relevant.
Removed:
lldb/trunk/www/lldb-coding-conventions.html
Modified:
lldb/trunk/www/sidebar.incl
lldb/trunk/www/source.html
Removed: lldb/trunk/www/lldb-coding-conventions.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/lldb-coding-conventions.html?rev=280891&view=auto
==============================================================================
--- lldb/trunk/www/lldb-coding-conventions.html (original)
+++ lldb/trunk/www/lldb-coding-conventions.html (removed)
@@ -1,152 +0,0 @@
-<!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>Include Order:</h3>
- <p>LLDB follows <a href="http://llvm.org/docs/CodingStandards.html#include-style">LLVM's include order</a>,
- with an addition for LLDB specific headers.</p>
- <ol class="arabic simple" id="local-private-headers">
- <span id="main-module-header"></span>
- <li>Main Module Header</li>
- <li>Local/Private Headers</li>
- <li><code class="docutils literal"><span class="pre">lldb/...</span></code></li>
- <li><code class="docutils literal"><span class="pre">llvm/...</span></code></li>
- <li>System <code class="docutils literal"><span class="pre">#include</span></code>s</li>
- </ol>
- <p>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.</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>
Modified: lldb/trunk/www/sidebar.incl
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/sidebar.incl?rev=280892&r1=280891&r2=280892&view=diff
==============================================================================
--- lldb/trunk/www/sidebar.incl (original)
+++ lldb/trunk/www/sidebar.incl Wed Sep 7 19:42:02 2016
@@ -47,7 +47,6 @@
<li><a href="/source.html">Source</a></li>
<li><a href="/build.html">Build</a></li>
<li><a href="/test.html">Test</a></li>
- <li><a href="/lldb-coding-conventions.html">Coding Conventions</a></li>
<li><a href="/SB-api-coding-rules.html">SB API Coding Rules</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>
Modified: lldb/trunk/www/source.html
URL: http://llvm.org/viewvc/llvm-project/lldb/trunk/www/source.html?rev=280892&r1=280891&r2=280892&view=diff
==============================================================================
--- lldb/trunk/www/source.html (original)
+++ lldb/trunk/www/source.html Wed Sep 7 19:42:02 2016
@@ -69,7 +69,6 @@
for information about authoring and uploading a patch. LLDB differs from the LLVM Developer Policy in
the following respects.
<ul>
- <li>Coding conventions. Refer to <a href="lldb-coding-conventions.html">LLDB Coding Conventions</a>.</li>
<li>
Test infrastructure. It is still important to submit tests with your patches, but LLDB uses a different
system for tests. Refer to the lldb/test folder on disk for examples of how to write tests.
More information about the lldb-commits
mailing list