diff options
author | Zhanyong Wan <wan@google.com> | 2010-12-02 05:10:07 +0000 |
---|---|---|
committer | Zhanyong Wan <wan@google.com> | 2010-12-02 05:10:07 +0000 |
commit | 7fcd4dcb98d2e2bec231e713aefd2cacc879dd33 (patch) | |
tree | 2d5a0f9463045bccd6cee4c63f20a22baa7383e2 /docs/CodingStandards.html | |
parent | 6db8a9f3fabefeb00163295f0611d09134651f3f (diff) | |
download | external_llvm-7fcd4dcb98d2e2bec231e713aefd2cacc879dd33.zip external_llvm-7fcd4dcb98d2e2bec231e713aefd2cacc879dd33.tar.gz external_llvm-7fcd4dcb98d2e2bec231e713aefd2cacc879dd33.tar.bz2 |
Add naming rules to the coding standards.
git-svn-id: https://llvm.org/svn/llvm-project/llvm/trunk@120689 91177308-0d34-0410-b5e6-96231b3b80d8
Diffstat (limited to 'docs/CodingStandards.html')
-rw-r--r-- | docs/CodingStandards.html | 67 |
1 files changed, 67 insertions, 0 deletions
diff --git a/docs/CodingStandards.html b/docs/CodingStandards.html index a242080..4af3c6a 100644 --- a/docs/CodingStandards.html +++ b/docs/CodingStandards.html @@ -51,6 +51,7 @@ </ol></li> <li><a href="#micro">The Low-Level Issues</a> <ol> + <li><a href="#ll_naming">Name Types, Functions, Variables, and Enumerators Properly</a></li> <li><a href="#ll_assert">Assert Liberally</a></li> <li><a href="#ll_ns_std">Do not use '<tt>using namespace std</tt>'</a></li> <li><a href="#ll_virtual_anch">Provide a virtual method anchor for @@ -809,6 +810,72 @@ locality.</p> <!-- _______________________________________________________________________ --> <div class="doc_subsubsection"> + <a name="ll_naming">Name Types, Functions, Variables, and Enumerators Properly</a> +</div> + +<div class="doc_text"> +<p>Poorly-chosen names mislead the reader and cause bugs. We cannot +stress enough how important it is to use <em>descriptive</em> names. +Pick names that match the semantics and role of the underlying +entities, within reason. Avoid abbreviations unless they are well +known.</p> + +<p>In general, names of types, functions, variables, and enumerators +should be in camel case (e.g. <tt>TextFileReader</tt> +and <tt>isLValue()</tt>). Type names (including classes, structs, +enums, typedefs, etc) should be nouns and start with an upper-case +letter (e.g. <tt>TextFileReader</tt>). Function names should be verb +phrases (as they represent actions) and start with a lower-case letter +(e.g. a predicate may be named <tt>isFoo()</tt> or <tt>hasBar()</tt>, +while the name of a command-like function should be imperative, +like <tt>openFile()</tt>).</p> + +<p>Enumerators and public member variables should start with an +upper-case letter, just like types. Unless the enumerators are +defined in their own small namespace or inside a class, they should +have a prefix. For example, <tt>enum ValueKind { ... };</tt> may +contain enumerators like +<tt>VK_Argument</tt>, <tt>VK_BasicBlock</tt>, etc. Enumerators that +are just convenience constants are exempt from the requirement for a +prefix. For instance:</p> +<div class="doc_code"> +<pre> +enum { + MaxSize = 42, + Density = 12 +}; +</pre> +</div> + +<p>As an exception, classes that mimic STL classes can have member names +in STL's style of lower-case words separated by underscores +(e.g. <tt>begin()</tt>, <tt>push_back()</tt>, and <tt>empty()</tt>).</p> + +<p>Here are some examples of bad and good names:</p> +<div class="doc_code"> +<pre> +class VehicleMaker { + ... + Factory<Tire> f; // Bad -- abbreviation and non-descriptive. + Factory<Tire> factory; // Better. + Factory<Tire> tireFactory; // Even better -- if VehicleMaker has more than one + // kind of factories. +}; + +Vehicle MakeVehicle(VehicleType Type) { + VehicleMaker m; // Might be OK if having a short life-span. + Tire tmp1 = m.makeTire(); // Bad -- 'tmp1' provides no information. + Light headlight = m.makeLight("head"); // Good -- descriptive. + ... +} +</pre> +</div> + +</div> + + +<!-- _______________________________________________________________________ --> +<div class="doc_subsubsection"> <a name="ll_assert">Assert Liberally</a> </div> |