[llvm-commits] [llvm] r158786 - in /llvm/trunk/docs: CodingStandards.html CodingStandards.rst development_process.rst

Sean Silva silvas at purdue.edu
Wed Jun 20 00:06:09 PDT 2012


Yay!!!

Thanks so much for doing this!

--Sean Silva

On Tue, Jun 19, 2012 at 7:57 PM, Bill Wendling <isanbard at gmail.com> wrote:

> Author: void
> Date: Tue Jun 19 21:57:56 2012
> New Revision: 158786
>
> URL: http://llvm.org/viewvc/llvm-project?rev=158786&view=rev
> Log:
> Sphinxify the CodingStandard documentation.
>
> Added:
>    llvm/trunk/docs/CodingStandards.rst
> Removed:
>    llvm/trunk/docs/CodingStandards.html
> Modified:
>    llvm/trunk/docs/development_process.rst
>
> Removed: llvm/trunk/docs/CodingStandards.html
> URL:
> http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/CodingStandards.html?rev=158785&view=auto
>
> ==============================================================================
> --- llvm/trunk/docs/CodingStandards.html (original)
> +++ llvm/trunk/docs/CodingStandards.html (removed)
> @@ -1,1568 +0,0 @@
> -<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
> -                      "http://www.w3.org/TR/html4/strict.dtd">
> -<html>
> -<head>
> -  <meta http-equiv="Content-Type" content="text/html; charset=utf-8">
> -  <link rel="stylesheet" href="_static/llvm.css" type="text/css">
> -  <title>LLVM Coding Standards</title>
> -</head>
> -<body>
> -
> -<h1>
> -  LLVM Coding Standards
> -</h1>
> -
> -<ol>
> -  <li><a href="#introduction">Introduction</a></li>
> -  <li><a href="#mechanicalissues">Mechanical Source Issues</a>
> -    <ol>
> -      <li><a href="#sourceformating">Source Code Formatting</a>
> -        <ol>
> -          <li><a href="#scf_commenting">Commenting</a></li>
> -          <li><a href="#scf_commentformat">Comment Formatting</a></li>
> -          <li><a href="#scf_includes"><tt>#include</tt> Style</a></li>
> -          <li><a href="#scf_codewidth">Source Code Width</a></li>
> -          <li><a href="#scf_spacestabs">Use Spaces Instead of
> Tabs</a></li>
> -          <li><a href="#scf_indentation">Indent Code Consistently</a></li>
> -        </ol></li>
> -      <li><a href="#compilerissues">Compiler Issues</a>
> -        <ol>
> -          <li><a href="#ci_warningerrors">Treat Compiler Warnings Like
> -              Errors</a></li>
> -          <li><a href="#ci_portable_code">Write Portable Code</a></li>
> -          <li><a href="#ci_rtti_exceptions">Do not use RTTI or
> Exceptions</a></li>
> -          <li><a href="#ci_static_ctors">Do not use Static
> Constructors</a></li>
> -          <li><a href="#ci_class_struct">Use of
> <tt>class</tt>/<tt>struct</tt> Keywords</a></li>
> -        </ol></li>
> -    </ol></li>
> -  <li><a href="#styleissues">Style Issues</a>
> -    <ol>
> -      <li><a href="#macro">The High-Level Issues</a>
> -        <ol>
> -          <li><a href="#hl_module">A Public Header File <b>is</b> a
> -              Module</a></li>
> -          <li><a href="#hl_dontinclude"><tt>#include</tt> as Little as
> Possible</a></li>
> -          <li><a href="#hl_privateheaders">Keep "internal" Headers
> -              Private</a></li>
> -          <li><a href="#hl_earlyexit">Use Early Exits and
> <tt>continue</tt> to Simplify
> -              Code</a></li>
> -          <li><a href="#hl_else_after_return">Don't use <tt>else</tt>
> after a
> -              <tt>return</tt></a></li>
> -          <li><a href="#hl_predicateloops">Turn Predicate Loops into
> Predicate
> -              Functions</a></li>
> -        </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
> -              classes in headers</a></li>
> -          <li><a href="#ll_end">Don't evaluate <tt>end()</tt> every time
> through a
> -              loop</a></li>
> -          <li><a href="#ll_iostream"><tt>#include <iostream></tt> is
> -              <em>forbidden</em></a></li>
> -          <li><a href="#ll_raw_ostream">Use <tt>raw_ostream</tt></a></li>
> -          <li><a href="#ll_avoidendl">Avoid <tt>std::endl</tt></a></li>
> -        </ol></li>
> -
> -      <li><a href="#nano">Microscopic Details</a>
> -        <ol>
> -          <li><a href="#micro_spaceparen">Spaces Before
> Parentheses</a></li>
> -          <li><a href="#micro_preincrement">Prefer Preincrement</a></li>
> -          <li><a href="#micro_namespaceindent">Namespace
> Indentation</a></li>
> -          <li><a href="#micro_anonns">Anonymous Namespaces</a></li>
> -        </ol></li>
> -
> -
> -    </ol></li>
> -  <li><a href="#seealso">See Also</a></li>
> -</ol>
> -
> -<div class="doc_author">
> -  <p>Written by <a href="mailto:sabre at nondot.org">Chris Lattner</a></p>
> -</div>
> -
> -
> -<!--
> *********************************************************************** -->
> -<h2><a name="introduction">Introduction</a></h2>
> -<!--
> *********************************************************************** -->
> -
> -<div>
> -
> -<p>This document attempts to describe a few coding standards that are
> being used
> -in the LLVM source tree.  Although no coding standards should be regarded
> as
> -absolute requirements to be followed in all instances, coding standards
> are
> -particularly important for large-scale code bases that follow a
> library-based
> -design (like LLVM).</p>
> -
> -<p>This document intentionally does not prescribe fixed standards for
> religious
> -issues such as brace placement and space usage.  For issues like this,
> follow
> -the golden rule:</p>
> -
> -<blockquote>
> -
> -<p><b><a name="goldenrule">If you are extending, enhancing, or bug fixing
> -already implemented code, use the style that is already being used so
> that the
> -source is uniform and easy to follow.</a></b></p>
> -
> -</blockquote>
> -
> -<p>Note that some code bases (e.g. libc++) have really good reasons to
> deviate
> -from the coding standards.  In the case of libc++, this is because the
> naming
> -and other conventions are dictated by the C++ standard.  If you think
> there is
> -a specific good reason to deviate from the standards here, please bring
> it up
> -on the LLVMdev mailing list.</p>
> -
> -<p>There are some conventions that are not uniformly followed in the code
> base
> -(e.g. the naming convention).  This is because they are relatively new,
> and a
> -lot of code was written before they were put in place.  Our long term
> goal is
> -for the entire codebase to follow the convention, but we explicitly <em>do
> -not</em> want patches that do large-scale reformating of existing code.
>  OTOH,
> -it is reasonable to rename the methods of a class if you're about to
> change it
> -in some other way.  Just do the reformating as a separate commit from the
> -functionality change. </p>
> -
> -<p>The ultimate goal of these guidelines is the increase readability and
> -maintainability of our common source base. If you have suggestions for
> topics to
> -be included, please mail them to <a
> -href="mailto:sabre at nondot.org">Chris</a>.</p>
> -
> -</div>
> -
> -<!--
> *********************************************************************** -->
> -<h2>
> -  <a name="mechanicalissues">Mechanical Source Issues</a>
> -</h2>
> -<!--
> *********************************************************************** -->
> -
> -<div>
> -
> -<!--
> ======================================================================= -->
> -<h3>
> -  <a name="sourceformating">Source Code Formatting</a>
> -</h3>
> -
> -<div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="scf_commenting">Commenting</a>
> -</h4>
> -
> -<div>
> -
> -<p>Comments are one critical part of readability and maintainability.
>  Everyone
> -knows they should comment their code, and so should you.  When writing
> comments,
> -write them as English prose, which means they should use proper
> capitalization,
> -punctuation, etc.  Aim to describe what a code is trying to do and why,
> not
> -"how" it does it at a micro level. Here are a few critical things to
> -document:</p>
> -
> -<h5>File Headers</h5>
> -
> -<div>
> -
> -<p>Every source file should have a header on it that describes the basic
> -purpose of the file.  If a file does not have a header, it should not be
> -checked into the tree.  The standard header looks like this:</p>
> -
> -<div class="doc_code">
> -<pre>
> -//===-- llvm/Instruction.h - Instruction class definition -------*- C++
> -*-===//
> -//
> -//                     The LLVM Compiler Infrastructure
> -//
> -// This file is distributed under the University of Illinois Open Source
> -// License. See LICENSE.TXT for details.
> -//
>
> -//===----------------------------------------------------------------------===//
> -//
> -// This file contains the declaration of the Instruction class, which is
> the
> -// base class for all of the VM instructions.
> -//
>
> -//===----------------------------------------------------------------------===//
> -</pre>
> -</div>
> -
> -<p>A few things to note about this particular format:  The "<tt>-*- C++
> --*-</tt>" string on the first line is there to tell Emacs that the source
> file
> -is a C++ file, not a C file (Emacs assumes <tt>.h</tt> files are C files
> by default).
> -Note that this tag is not necessary in <tt>.cpp</tt> files.  The name of
> the file is also
> -on the first line, along with a very short description of the purpose of
> the
> -file.  This is important when printing out code and flipping though lots
> of
> -pages.</p>
> -
> -<p>The next section in the file is a concise note that defines the license
> -that the file is released under.  This makes it perfectly clear what
> terms the
> -source code can be distributed under and should not be modified in any
> way.</p>
> -
> -<p>The main body of the description does not have to be very long in most
> cases.
> -Here it's only two lines.  If an algorithm is being implemented or
> something
> -tricky is going on, a reference to the paper where it is published should
> be
> -included, as well as any notes or "gotchas" in the code to watch out
> for.</p>
> -
> -</div>
> -
> -<h5>Class overviews</h5>
> -
> -<p>Classes are one fundamental part of a good object oriented design.  As
> such,
> -a class definition should have a comment block that explains what the
> class is
> -used for and how it works.  Every non-trivial class is expected to have a
> -doxygen comment block.</p>
> -
> -
> -<h5>Method information</h5>
> -
> -<div>
> -
> -<p>Methods defined in a class (as well as any global functions) should
> also be
> -documented properly.  A quick note about what it does and a description
> of the
> -borderline behaviour is all that is necessary here (unless something
> -particularly tricky or insidious is going on).  The hope is that people
> can
> -figure out how to use your interfaces without reading the code itself.</p>
> -
> -<p>Good things to talk about here are what happens when something
> unexpected
> -happens: does the method return null?  Abort?  Format your hard disk?</p>
> -
> -</div>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="scf_commentformat">Comment Formatting</a>
> -</h4>
> -
> -<div>
> -
> -<p>In general, prefer C++ style (<tt>//</tt>) comments.  They take less
> space,
> -require less typing, don't have nesting problems, etc.  There are a few
> cases
> -when it is useful to use C style (<tt>/* */</tt>) comments however:</p>
> -
> -<ol>
> -  <li>When writing C code: Obviously if you are writing C code, use C
> style
> -      comments.</li>
> -  <li>When writing a header file that may be <tt>#include</tt>d by a C
> source
> -      file.</li>
> -  <li>When writing a source file that is used by a tool that only accepts
> C
> -      style comments.</li>
> -</ol>
> -
> -<p>To comment out a large block of code, use <tt>#if 0</tt> and
> <tt>#endif</tt>.
> -These nest properly and are better behaved in general than C style
> comments.</p>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="scf_includes"><tt>#include</tt> Style</a>
> -</h4>
> -
> -<div>
> -
> -<p>Immediately after the <a href="#scf_commenting">header file
> comment</a> (and
> -include guards if working on a header file), the <a
> -href="#hl_dontinclude">minimal</a> list of <tt>#include</tt>s required by
> the
> -file should be listed.  We prefer these <tt>#include</tt>s to be listed
> in this
> -order:</p>
> -
> -<ol>
> -  <li><a href="#mmheader">Main Module Header</a></li>
> -  <li><a href="#hl_privateheaders">Local/Private Headers</a></li>
> -  <li><tt>llvm/*</tt></li>
> -  <li><tt>llvm/Analysis/*</tt></li>
> -  <li><tt>llvm/Assembly/*</tt></li>
> -  <li><tt>llvm/Bitcode/*</tt></li>
> -  <li><tt>llvm/CodeGen/*</tt></li>
> -  <li>...</li>
> -  <li><tt>Support/*</tt></li>
> -  <li><tt>Config/*</tt></li>
> -  <li>System <tt>#includes</tt></li>
> -</ol>
> -
> -<p>and each category should be sorted by name.</p>
> -
> -<p><a name="mmheader">The "Main Module Header"</a> file applies to
> <tt>.cpp</tt> files
> -which implement an interface defined by a <tt>.h</tt> file.  This
> <tt>#include</tt>
> -should always be included <b>first</b> regardless of where it lives on
> the file
> -system.  By including a header file first in the <tt>.cpp</tt> files that
> implement the
> -interfaces, we ensure that the header does not have any hidden
> dependencies
> -which are not explicitly #included in the header, but should be.  It is
> also a
> -form of documentation in the <tt>.cpp</tt> file to indicate where the
> interfaces it
> -implements are defined.</p>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="scf_codewidth">Source Code Width</a>
> -</h4>
> -
> -<div>
> -
> -<p>Write your code to fit within 80 columns of text.  This helps those of
> us who
> -like to print out code and look at your code in an xterm without resizing
> -it.</p>
> -
> -<p>The longer answer is that there must be some limit to the width of the
> code
> -in order to reasonably allow developers to have multiple files
> side-by-side in
> -windows on a modest display.  If you are going to pick a width limit, it
> is
> -somewhat arbitrary but you might as well pick something standard.  Going
> with
> -90 columns (for example) instead of 80 columns wouldn't add any
> significant
> -value and would be detrimental to printing out code.  Also many other
> projects
> -have standardized on 80 columns, so some people have already configured
> their
> -editors for it (vs something else, like 90 columns).</p>
> -
> -<p>This is one of many contentious issues in coding standards, but it is
> not up
> -for debate.</p>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="scf_spacestabs">Use Spaces Instead of Tabs</a>
> -</h4>
> -
> -<div>
> -
> -<p>In all cases, prefer spaces to tabs in source files.  People have
> different
> -preferred indentation levels, and different styles of indentation that
> they
> -like; this is fine.  What isn't fine is that different editors/viewers
> expand
> -tabs out to different tab stops.  This can cause your code to look
> completely
> -unreadable, and it is not worth dealing with.</p>
> -
> -<p>As always, follow the <a href="#goldenrule">Golden Rule</a> above:
> follow the
> -style of existing code if you are modifying and extending it.  If you
> like four
> -spaces of indentation, <b>DO NOT</b> do that in the middle of a chunk of
> code
> -with two spaces of indentation.  Also, do not reindent a whole source
> file: it
> -makes for incredible diffs that are absolutely worthless.</p>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="scf_indentation">Indent Code Consistently</a>
> -</h4>
> -
> -<div>
> -
> -<p>Okay, in your first year of programming you were told that indentation
> is
> -important.  If you didn't believe and internalize this then, now is the
> time.
> -Just do it.</p>
> -
> -</div>
> -
> -</div>
> -
> -<!--
> ======================================================================= -->
> -<h3>
> -  <a name="compilerissues">Compiler Issues</a>
> -</h3>
> -
> -<div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="ci_warningerrors">Treat Compiler Warnings Like Errors</a>
> -</h4>
> -
> -<div>
> -
> -<p>If your code has compiler warnings in it, something is wrong —
> you
> -aren't casting values correctly, your have "questionable" constructs in
> your
> -code, or you are doing something legitimately wrong.  Compiler warnings
> can
> -cover up legitimate errors in output and make dealing with a translation
> unit
> -difficult.</p>
> -
> -<p>It is not possible to prevent all warnings from all compilers, nor is
> it
> -desirable.  Instead, pick a standard compiler (like <tt>gcc</tt>) that
> provides
> -a good thorough set of warnings, and stick to it.  At least in the case of
> -<tt>gcc</tt>, it is possible to work around any spurious errors by
> changing the
> -syntax of the code slightly.  For example, a warning that annoys me
> occurs when
> -I write code like this:</p>
> -
> -<div class="doc_code">
> -<pre>
> -if (V = getValue()) {
> -  ...
> -}
> -</pre>
> -</div>
> -
> -<p><tt>gcc</tt> will warn me that I probably want to use the <tt>==</tt>
> -operator, and that I probably mistyped it.  In most cases, I haven't, and
> I
> -really don't want the spurious errors.  To fix this particular problem, I
> -rewrite the code like this:</p>
> -
> -<div class="doc_code">
> -<pre>
> -if ((V = getValue())) {
> -  ...
> -}
> -</pre>
> -</div>
> -
> -<p>which shuts <tt>gcc</tt> up.  Any <tt>gcc</tt> warning that annoys you
> can
> -be fixed by massaging the code appropriately.</p>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="ci_portable_code">Write Portable Code</a>
> -</h4>
> -
> -<div>
> -
> -<p>In almost all cases, it is possible and within reason to write
> completely
> -portable code.  If there are cases where it isn't possible to write
> portable
> -code, isolate it behind a well defined (and well documented)
> interface.</p>
> -
> -<p>In practice, this means that you shouldn't assume much about the host
> -compiler, and Visual Studio tends to be the lowest common denominator.
> -If advanced features are used, they should only be an implementation
> detail of
> -a library which has a simple exposed API, and preferably be buried in
> -libSystem.</p>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -<a name="ci_rtti_exceptions">Do not use RTTI or Exceptions</a>
> -</h4>
> -<div>
> -
> -<p>In an effort to reduce code and executable size, LLVM does not use RTTI
> -(e.g. <tt>dynamic_cast<></tt>) or exceptions.  These two language
> features
> -violate the general C++ principle of <i>"you only pay for what you
> use"</i>,
> -causing executable bloat even if exceptions are never used in the code
> base, or
> -if RTTI is never used for a class.  Because of this, we turn them off
> globally
> -in the code.</p>
> -
> -<p>That said, LLVM does make extensive use of a hand-rolled form of RTTI
> that
> -use templates like <a
> href="ProgrammersManual.html#isa"><tt>isa<></tt>,
> -<tt>cast<></tt>, and <tt>dyn_cast<></tt></a>.  This form of
> RTTI is
> -opt-in and can be added to any class.  It is also substantially more
> efficient
> -than <tt>dynamic_cast<></tt>.</p>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -<a name="ci_static_ctors">Do not use Static Constructors</a>
> -</h4>
> -<div>
> -
> -<p>Static constructors and destructors (e.g. global variables whose types
> have
> -a constructor or destructor) should not be added to the code base, and
> should be
> -removed wherever possible.  Besides <a
> -href="http://yosefk.com/c++fqa/ctors.html#fqa-10.12">well known
> problems</a>
> -where the order of initialization is undefined between globals in
> different
> -source files, the entire concept of static constructors is at odds with
> the
> -common use case of LLVM as a library linked into a larger application.</p>
> -
> -<p>Consider the use of LLVM as a JIT linked into another application
> (perhaps
> -for <a href="http://llvm.org/Users.html">OpenGL, custom languages</a>,
> -<a href="http://llvm.org/devmtg/2010-11/Gritz-OpenShadingLang.pdf">shaders
> in
> -movies</a>, etc).  Due to the design of static constructors, they must be
> -executed at startup time of the entire application, regardless of whether
> or
> -how LLVM is used in that larger application.  There are two problems with
> -this:</p>
> -
> -<ol>
> -  <li>The time to run the static constructors impacts startup time of
> -    applications — a critical time for GUI apps, among others.</li>
> -
> -  <li>The static constructors cause the app to pull many extra pages of
> memory
> -    off the disk: both the code for the constructor in each <tt>.o</tt>
> file and
> -    the small amount of data that gets touched. In addition,
> touched/dirty pages
> -    put more pressure on the VM system on low-memory machines.</li>
> -</ol>
> -
> -<p>We would really like for there to be zero cost for linking in an
> additional
> -LLVM target or other library into an application, but static constructors
> -violate this goal.</p>
> -
> -<p>That said, LLVM unfortunately does contain static constructors.  It
> would be
> -a <a href="http://llvm.org/PR11944">great project</a> for someone to
> purge all
> -static constructors from LLVM, and then enable the
> -<tt>-Wglobal-constructors</tt> warning flag (when building with Clang) to
> ensure
> -we do not regress in the future.
> -</p>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -<a name="ci_class_struct">Use of <tt>class</tt> and <tt>struct</tt>
> Keywords</a>
> -</h4>
> -<div>
> -
> -<p>In C++, the <tt>class</tt> and <tt>struct</tt> keywords can be used
> almost
> -interchangeably. The only difference is when they are used to declare a
> class:
> -<tt>class</tt> makes all members private by default while <tt>struct</tt>
> makes
> -all members public by default.</p>
> -
> -<p>Unfortunately, not all compilers follow the rules and some will
> generate
> -different symbols based on whether <tt>class</tt> or <tt>struct</tt> was
> used to
> -declare the symbol.  This can lead to problems at link time.</p>
> -
> -<p>So, the rule for LLVM is to always use the <tt>class</tt> keyword,
> unless
> -<b>all</b> members are public and the type is a C++
> -<a href="http://en.wikipedia.org/wiki/Plain_old_data_structure">POD</a>
> type, in
> -which case <tt>struct</tt> is allowed.</p>
> -
> -</div>
> -
> -</div>
> -
> -</div>
> -
> -<!--
> *********************************************************************** -->
> -<h2>
> -  <a name="styleissues">Style Issues</a>
> -</h2>
> -<!--
> *********************************************************************** -->
> -
> -<div>
> -
> -<!--
> ======================================================================= -->
> -<h3>
> -  <a name="macro">The High-Level Issues</a>
> -</h3>
> -<!--
> ======================================================================= -->
> -
> -<div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="hl_module">A Public Header File <b>is</b> a Module</a>
> -</h4>
> -
> -<div>
> -
> -<p>C++ doesn't do too well in the modularity department.  There is no real
> -encapsulation or data hiding (unless you use expensive protocol classes),
> but it
> -is what we have to work with.  When you write a public header file (in
> the LLVM
> -source tree, they live in the top level "<tt>include</tt>" directory),
> you are
> -defining a module of functionality.</p>
> -
> -<p>Ideally, modules should be completely independent of each other, and
> their
> -header files should only <tt>#include</tt> the absolute minimum number of
> -headers possible. A module is not just a class, a function, or a
> -namespace: <a href="http://www.cuj.com/articles/2000/0002/0002c/0002c.htm
> ">it's
> -a collection of these</a> that defines an interface.  This interface may
> be
> -several functions, classes, or data structures, but the important issue
> is how
> -they work together.</p>
> -
> -<p>In general, a module should be implemented by one or more <tt>.cpp</tt>
> -files.  Each of these <tt>.cpp</tt> files should include the header that
> defines
> -their interface first.  This ensures that all of the dependences of the
> module
> -header have been properly added to the module header itself, and are not
> -implicit.  System headers should be included after user headers for a
> -translation unit.</p>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="hl_dontinclude"><tt>#include</tt> as Little as Possible</a>
> -</h4>
> -
> -<div>
> -
> -<p><tt>#include</tt> hurts compile time performance.  Don't do it unless
> you
> -have to, especially in header files.</p>
> -
> -<p>But wait! Sometimes you need to have the definition of a class to use
> it, or
> -to inherit from it.  In these cases go ahead and <tt>#include</tt> that
> header
> -file.  Be aware however that there are many cases where you don't need to
> have
> -the full definition of a class.  If you are using a pointer or reference
> to a
> -class, you don't need the header file.  If you are simply returning a
> class
> -instance from a prototyped function or method, you don't need it.  In
> fact, for
> -most cases, you simply don't need the definition of a class. And not
> -<tt>#include</tt>'ing speeds up compilation.</p>
> -
> -<p>It is easy to try to go too overboard on this recommendation, however.
>  You
> -<b>must</b> include all of the header files that you are using —
> you can
> -include them either directly or indirectly (through another header file).
>  To
> -make sure that you don't accidentally forget to include a header file in
> your
> -module header, make sure to include your module header <b>first</b> in the
> -implementation file (as mentioned above).  This way there won't be any
> hidden
> -dependencies that you'll find out about later.</p>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="hl_privateheaders">Keep "Internal" Headers Private</a>
> -</h4>
> -
> -<div>
> -
> -<p>Many modules have a complex implementation that causes them to use
> more than
> -one implementation (<tt>.cpp</tt>) file.  It is often tempting to put the
> -internal communication interface (helper classes, extra functions, etc)
> in the
> -public module header file.  Don't do this!</p>
> -
> -<p>If you really need to do something like this, put a private header
> file in
> -the same directory as the source files, and include it locally.  This
> ensures
> -that your private interface remains private and undisturbed by
> outsiders.</p>
> -
> -<p>Note however, that it's okay to put extra implementation methods in a
> public
> -class itself. Just make them private (or protected) and all is well.</p>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="hl_earlyexit">Use Early Exits and <tt>continue</tt> to
> Simplify Code</a>
> -</h4>
> -
> -<div>
> -
> -<p>When reading code, keep in mind how much state and how many previous
> -decisions have to be remembered by the reader to understand a block of
> code.
> -Aim to reduce indentation where possible when it doesn't make it more
> difficult
> -to understand the code.  One great way to do this is by making use of
> early
> -exits and the <tt>continue</tt> keyword in long loops.  As an example of
> using
> -an early exit from a function, consider this "bad" code:</p>
> -
> -<div class="doc_code">
> -<pre>
> -Value *DoSomething(Instruction *I) {
> -  if (!isa<TerminatorInst>(I) &&
> -      I->hasOneUse() && SomeOtherThing(I)) {
> -    ... some long code ....
> -  }
> -
> -  return 0;
> -}
> -</pre>
> -</div>
> -
> -<p>This code has several problems if the body of the '<tt>if</tt>' is
> large.
> -When you're looking at the top of the function, it isn't immediately
> clear that
> -this <em>only</em> does interesting things with non-terminator
> instructions, and
> -only applies to things with the other predicates.  Second, it is
> relatively
> -difficult to describe (in comments) why these predicates are important
> because
> -the <tt>if</tt> statement makes it difficult to lay out the comments.
>  Third,
> -when you're deep within the body of the code, it is indented an extra
> level.
> -Finally, when reading the top of the function, it isn't clear what the
> result is
> -if the predicate isn't true; you have to read to the end of the function
> to know
> -that it returns null.</p>
> -
> -<p>It is much preferred to format the code like this:</p>
> -
> -<div class="doc_code">
> -<pre>
> -Value *DoSomething(Instruction *I) {
> -  // Terminators never need 'something' done to them because ...
> -  if (isa<TerminatorInst>(I))
> -    return 0;
> -
> -  // We conservatively avoid transforming instructions with multiple uses
> -  // because goats like cheese.
> -  if (!I->hasOneUse())
> -    return 0;
> -
> -  // This is really just here for example.
> -  if (!SomeOtherThing(I))
> -    return 0;
> -
> -  ... some long code ....
> -}
> -</pre>
> -</div>
> -
> -<p>This fixes these problems.  A similar problem frequently happens in
> <tt>for</tt>
> -loops.  A silly example is something like this:</p>
> -
> -<div class="doc_code">
> -<pre>
> -  for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II !=
> E; ++II) {
> -    if (BinaryOperator *BO = dyn_cast<BinaryOperator>(II)) {
> -      Value *LHS = BO->getOperand(0);
> -      Value *RHS = BO->getOperand(1);
> -      if (LHS != RHS) {
> -        ...
> -      }
> -    }
> -  }
> -</pre>
> -</div>
> -
> -<p>When you have very, very small loops, this sort of structure is fine.
> But if
> -it exceeds more than 10-15 lines, it becomes difficult for people to read
> and
> -understand at a glance. The problem with this sort of code is that it
> gets very
> -nested very quickly. Meaning that the reader of the code has to keep a
> lot of
> -context in their brain to remember what is going immediately on in the
> loop,
> -because they don't know if/when the <tt>if</tt> conditions will have
> elses etc.
> -It is strongly preferred to structure the loop like this:</p>
> -
> -<div class="doc_code">
> -<pre>
> -  for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II !=
> E; ++II) {
> -    BinaryOperator *BO = dyn_cast<BinaryOperator>(II);
> -    if (!BO) continue;
> -
> -    Value *LHS = BO->getOperand(0);
> -    Value *RHS = BO->getOperand(1);
> -    if (LHS == RHS) continue;
> -
> -    ...
> -  }
> -</pre>
> -</div>
> -
> -<p>This has all the benefits of using early exits for functions: it
> reduces
> -nesting of the loop, it makes it easier to describe why the conditions
> are true,
> -and it makes it obvious to the reader that there is no <tt>else</tt>
> coming up
> -that they have to push context into their brain for.  If a loop is large,
> this
> -can be a big understandability win.</p>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="hl_else_after_return">Don't use <tt>else</tt> after a
> <tt>return</tt></a>
> -</h4>
> -
> -<div>
> -
> -<p>For similar reasons above (reduction of indentation and easier
> reading),
> -please do not use '<tt>else</tt>' or '<tt>else if</tt>' after something
> that
> -interrupts control flow — like <tt>return</tt>, <tt>break</tt>,
> -<tt>continue</tt>, <tt>goto</tt>, etc. For example, this is
> <em>bad</em>:</p>
> -
> -<div class="doc_code">
> -<pre>
> -  case 'J': {
> -    if (Signed) {
> -      Type = Context.getsigjmp_bufType();
> -      if (Type.isNull()) {
> -        Error = ASTContext::GE_Missing_sigjmp_buf;
> -        return QualType();
> -      <b>} else {
> -        break;
> -      }</b>
> -    } else {
> -      Type = Context.getjmp_bufType();
> -      if (Type.isNull()) {
> -        Error = ASTContext::GE_Missing_jmp_buf;
> -        return QualType();
> -      <b>} else {
> -        break;
> -      }</b>
> -    }
> -  }
> -  }
> -</pre>
> -</div>
> -
> -<p>It is better to write it like this:</p>
> -
> -<div class="doc_code">
> -<pre>
> -  case 'J':
> -    if (Signed) {
> -      Type = Context.getsigjmp_bufType();
> -      if (Type.isNull()) {
> -        Error = ASTContext::GE_Missing_sigjmp_buf;
> -        return QualType();
> -      }
> -    } else {
> -      Type = Context.getjmp_bufType();
> -      if (Type.isNull()) {
> -        Error = ASTContext::GE_Missing_jmp_buf;
> -        return QualType();
> -      }
> -    }
> -    <b>break;</b>
> -</pre>
> -</div>
> -
> -<p>Or better yet (in this case) as:</p>
> -
> -<div class="doc_code">
> -<pre>
> -  case 'J':
> -    if (Signed)
> -      Type = Context.getsigjmp_bufType();
> -    else
> -      Type = Context.getjmp_bufType();
> -
> -    if (Type.isNull()) {
> -      Error = Signed ? ASTContext::GE_Missing_sigjmp_buf :
> -                       ASTContext::GE_Missing_jmp_buf;
> -      return QualType();
> -    }
> -    <b>break;</b>
> -</pre>
> -</div>
> -
> -<p>The idea is to reduce indentation and the amount of code you have to
> keep
> -track of when reading the code.</p>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="hl_predicateloops">Turn Predicate Loops into Predicate
> Functions</a>
> -</h4>
> -
> -<div>
> -
> -<p>It is very common to write small loops that just compute a boolean
> value.
> -There are a number of ways that people commonly write these, but an
> example of
> -this sort of thing is:</p>
> -
> -<div class="doc_code">
> -<pre>
> -  <b>bool FoundFoo = false;</b>
> -  for (unsigned i = 0, e = BarList.size(); i != e; ++i)
> -    if (BarList[i]->isFoo()) {
> -      <b>FoundFoo = true;</b>
> -      break;
> -    }
> -
> -  <b>if (FoundFoo) {</b>
> -    ...
> -  }
> -</pre>
> -</div>
> -
> -<p>This sort of code is awkward to write, and is almost always a bad sign.
> -Instead of this sort of loop, we strongly prefer to use a predicate
> function
> -(which may be <a href="#micro_anonns">static</a>) that uses
> -<a href="#hl_earlyexit">early exits</a> to compute the predicate.  We
> prefer
> -the code to be structured like this:</p>
> -
> -<div class="doc_code">
> -<pre>
> -/// ListContainsFoo - Return true if the specified list has an element
> that is
> -/// a foo.
> -static bool ListContainsFoo(const std::vector<Bar*> &List) {
> -  for (unsigned i = 0, e = List.size(); i != e; ++i)
> -    if (List[i]->isFoo())
> -      return true;
> -  return false;
> -}
> -...
> -
> -  <b>if (ListContainsFoo(BarList)) {</b>
> -    ...
> -  }
> -</pre>
> -</div>
> -
> -<p>There are many reasons for doing this: it reduces indentation and
> factors out
> -code which can often be shared by other code that checks for the same
> predicate.
> -More importantly, it <em>forces you to pick a name</em> for the function,
> and
> -forces you to write a comment for it.  In this silly example, this
> doesn't add
> -much value.  However, if the condition is complex, this can make it a lot
> easier
> -for the reader to understand the code that queries for this predicate.
>  Instead
> -of being faced with the in-line details of how we check to see if the
> BarList
> -contains a foo, we can trust the function name and continue reading with
> better
> -locality.</p>
> -
> -</div>
> -
> -</div>
> -
> -<!--
> ======================================================================= -->
> -<h3>
> -  <a name="micro">The Low-Level Issues</a>
> -</h3>
> -<!--
> ======================================================================= -->
> -
> -<div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="ll_naming">
> -    Name Types, Functions, Variables, and Enumerators Properly
> -  </a>
> -</h4>
> -
> -<div>
> -
> -<p>Poorly-chosen names can 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.  After picking a good name,
> make sure
> -to use consistent capitalization for the name, as inconsistency requires
> clients
> -to either memorize the APIs or to look it up to find the exact
> spelling.</p>
> -
> -<p>In general, names should be in camel case (e.g. <tt>TextFileReader</tt>
> -and <tt>isLValue()</tt>).  Different kinds of declarations have different
> -rules:</p>
> -
> -<ul>
> -<li><p><b>Type names</b> (including classes, structs, enums, typedefs,
> etc)
> -    should be nouns and start with an upper-case letter (e.g.
> -    <tt>TextFileReader</tt>).</p></li>
> -
> -<li><p><b>Variable names</b> should be nouns (as they represent state).
>  The
> -    name should be camel case, and start with an upper case letter (e.g.
> -    <tt>Leader</tt> or <tt>Boats</tt>).</p></li>
> -
> -<li><p><b>Function names</b> should be verb phrases (as they represent
> -    actions), and command-like function should be imperative.  The name
> should
> -    be camel case, and start with a lower case letter (e.g.
> <tt>openFile()</tt>
> -    or <tt>isFoo()</tt>).</p></li>
> -
> -<li><p><b>Enum declarations</b> (e.g. <tt>enum Foo {...}</tt>) are types,
> so
> -    they should follow the naming conventions for types.  A common use
> for enums
> -    is as a discriminator for a union, or an indicator of a subclass.
>  When an
> -    enum is used for something like this, it should have a <tt>Kind</tt>
> suffix
> -    (e.g. <tt>ValueKind</tt>).</p></li>
> -
> -<li><p><b>Enumerators</b> (e.g. <tt>enum { Foo, Bar }</tt>) and <b>public
> member
> -    variables</b> should start with an upper-case letter, just like types.
> -    Unless the enumerators are defined in their own small namespace or
> inside a
> -    class, enumerators should have a prefix corresponding to the enum
> -    declaration name.  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>
> -</li>
> -
> -</ul>
> -
> -<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 good and bad 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>
> -
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="ll_assert">Assert Liberally</a>
> -</h4>
> -
> -<div>
> -
> -<p>Use the "<tt>assert</tt>" macro to its fullest.  Check all of your
> -preconditions and assumptions, you never know when a bug (not necessarily
> even
> -yours) might be caught early by an assertion, which reduces debugging time
> -dramatically.  The "<tt><cassert></tt>" header file is probably
> already
> -included by the header files you are using, so it doesn't cost anything
> to use
> -it.</p>
> -
> -<p>To further assist with debugging, make sure to put some kind of error
> message
> -in the assertion statement, which is printed if the assertion is tripped.
> This
> -helps the poor debugger make sense of why an assertion is being made and
> -enforced, and hopefully what to do about it.  Here is one complete
> example:</p>
> -
> -<div class="doc_code">
> -<pre>
> -inline Value *getOperand(unsigned i) {
> -  assert(i < Operands.size() && "getOperand() out of range!");
> -  return Operands[i];
> -}
> -</pre>
> -</div>
> -
> -<p>Here are more examples:</p>
> -
> -<div class="doc_code">
> -<pre>
> -assert(Ty->isPointerType() && "Can't allocate a non pointer
> type!");
> -
> -assert((Opcode == Shl || Opcode == Shr) && "ShiftInst Opcode
> invalid!");
> -
> -assert(idx < getNumSuccessors() && "Successor # out of
> range!");
> -
> -assert(V1.getType() == V2.getType() && "Constant types must be
> identical!");
> -
> -assert(isa<PHINode>(Succ->front()) && "Only works on
> PHId BBs!");
> -</pre>
> -</div>
> -
> -<p>You get the idea.</p>
> -
> -<p>Please be aware that, when adding assert statements, not all compilers
> are aware of
> -the semantics of the assert.  In some places, asserts are used to
> indicate a piece of
> -code that should not be reached.  These are typically of the form:</p>
> -
> -<div class="doc_code">
> -<pre>
> -assert(0 && "Some helpful error message");
> -</pre>
> -</div>
> -
> -<p>When used in a function that returns a value, they should be followed
> with a return
> -statement and a comment indicating that this line is never reached.  This
> will prevent
> -a compiler which is unable to deduce that the assert statement never
> returns from
> -generating a warning.</p>
> -
> -<div class="doc_code">
> -<pre>
> -assert(0 && "Some helpful error message");
> -// Not reached
> -return 0;
> -</pre>
> -</div>
> -
> -<p>Another issue is that values used only by assertions will produce an
> "unused
> -value" warning when assertions are disabled.  For example, this code will
> -warn:</p>
> -
> -<div class="doc_code">
> -<pre>
> -unsigned Size = V.size();
> -assert(Size > 42 && "Vector smaller than it should be");
> -
> -bool NewToSet = Myset.insert(Value);
> -assert(NewToSet && "The value shouldn't be in the set yet");
> -</pre>
> -</div>
> -
> -<p>These are two interesting different cases. In the first case, the call
> to
> -V.size() is only useful for the assert, and we don't want it executed when
> -assertions are disabled.  Code like this should move the call into the
> assert
> -itself.  In the second case, the side effects of the call must happen
> whether
> -the assert is enabled or not.  In this case, the value should be cast to
> void to
> -disable the warning.  To be specific, it is preferred to write the code
> like
> -this:</p>
> -
> -<div class="doc_code">
> -<pre>
> -assert(V.size() > 42 && "Vector smaller than it should be");
> -
> -bool NewToSet = Myset.insert(Value); (void)NewToSet;
> -assert(NewToSet && "The value shouldn't be in the set yet");
> -</pre>
> -</div>
> -
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="ll_ns_std">Do Not Use '<tt>using namespace std</tt>'</a>
> -</h4>
> -
> -<div>
> -
> -<p>In LLVM, we prefer to explicitly prefix all identifiers from the
> standard
> -namespace with an "<tt>std::</tt>" prefix, rather than rely on
> -"<tt>using namespace std;</tt>".</p>
> -
> -<p> In header files, adding a '<tt>using namespace XXX</tt>' directive
> pollutes
> -the namespace of any source file that <tt>#include</tt>s the header.
>  This is
> -clearly a bad thing.</p>
> -
> -<p>In implementation files (e.g. <tt>.cpp</tt> files), the rule is more
> of a stylistic
> -rule, but is still important.  Basically, using explicit namespace
> prefixes
> -makes the code <b>clearer</b>, because it is immediately obvious what
> facilities
> -are being used and where they are coming from. And <b>more portable</b>,
> because
> -namespace clashes cannot occur between LLVM code and other namespaces.
>  The
> -portability rule is important because different standard library
> implementations
> -expose different symbols (potentially ones they shouldn't), and future
> revisions
> -to the C++ standard will add more symbols to the <tt>std</tt> namespace.
>  As
> -such, we never use '<tt>using namespace std;</tt>' in LLVM.</p>
> -
> -<p>The exception to the general rule (i.e. it's not an exception for
> -the <tt>std</tt> namespace) is for implementation files.  For example,
> all of
> -the code in the LLVM project implements code that lives in the 'llvm'
> namespace.
> -As such, it is ok, and actually clearer, for the <tt>.cpp</tt> files to
> have a
> -'<tt>using namespace llvm;</tt>' directive at the top, after the
> -<tt>#include</tt>s.  This reduces indentation in the body of the file for
> source
> -editors that indent based on braces, and keeps the conceptual context
> cleaner.
> -The general form of this rule is that any <tt>.cpp</tt> file that
> implements
> -code in any namespace may use that namespace (and its parents'), but
> should not
> -use any others.</p>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="ll_virtual_anch">
> -    Provide a Virtual Method Anchor for Classes in Headers
> -  </a>
> -</h4>
> -
> -<div>
> -
> -<p>If a class is defined in a header file and has a v-table (either it has
> -virtual methods or it derives from classes with virtual methods), it must
> -always have at least one out-of-line virtual method in the class.  Without
> -this, the compiler will copy the vtable and RTTI into every <tt>.o</tt>
> file
> -that <tt>#include</tt>s the header, bloating <tt>.o</tt> file sizes and
> -increasing link times.</p>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="ll_end">Don't evaluate <tt>end()</tt> every time through a
> loop</a>
> -</h4>
> -
> -<div>
> -
> -<p>Because C++ doesn't have a standard "<tt>foreach</tt>" loop (though it
> can be
> -emulated with macros and may be coming in C++'0x) we end up writing a lot
> of
> -loops that manually iterate from begin to end on a variety of containers
> or
> -through other data structures.  One common mistake is to write a loop in
> this
> -style:</p>
> -
> -<div class="doc_code">
> -<pre>
> -  BasicBlock *BB = ...
> -  for (BasicBlock::iterator I = BB->begin(); I != <b>BB->end()</b>; ++I)
> -     ... use I ...
> -</pre>
> -</div>
> -
> -<p>The problem with this construct is that it evaluates
> "<tt>BB->end()</tt>"
> -every time through the loop.  Instead of writing the loop like this, we
> strongly
> -prefer loops to be written so that they evaluate it once before the loop
> starts.
> -A convenient way to do this is like so:</p>
> -
> -<div class="doc_code">
> -<pre>
> -  BasicBlock *BB = ...
> -  for (BasicBlock::iterator I = BB->begin(), E = <b>BB->end()</b>; I !=
> E; ++I)
> -     ... use I ...
> -</pre>
> -</div>
> -
> -<p>The observant may quickly point out that these two loops may have
> different
> -semantics: if the container (a basic block in this case) is being
> mutated, then
> -"<tt>BB->end()</tt>" may change its value every time through the loop and
> the
> -second loop may not in fact be correct.  If you actually do depend on this
> -behavior, please write the loop in the first form and add a comment
> indicating
> -that you did it intentionally.</p>
> -
> -<p>Why do we prefer the second form (when correct)?  Writing the loop in
> the
> -first form has two problems. First it may be less efficient than
> evaluating it
> -at the start of the loop.  In this case, the cost is probably minor
> — a
> -few extra loads every time through the loop.  However, if the base
> expression is
> -more complex, then the cost can rise quickly.  I've seen loops where the
> end
> -expression was actually something like: "<tt>SomeMap[x]->end()</tt>" and
> map
> -lookups really aren't cheap.  By writing it in the second form
> consistently, you
> -eliminate the issue entirely and don't even have to think about it.</p>
> -
> -<p>The second (even bigger) issue is that writing the loop in the first
> form
> -hints to the reader that the loop is mutating the container (a fact that a
> -comment would handily confirm!).  If you write the loop in the second
> form, it
> -is immediately obvious without even looking at the body of the loop that
> the
> -container isn't being modified, which makes it easier to read the code and
> -understand what it does.</p>
> -
> -<p>While the second form of the loop is a few extra keystrokes, we do
> strongly
> -prefer it.</p>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="ll_iostream"><tt>#include <iostream></tt> is
> Forbidden</a>
> -</h4>
> -
> -<div>
> -
> -<p>The use of <tt>#include <iostream></tt> in library files is
> -hereby <b><em>forbidden</em></b>, because many common implementations
> -transparently inject a <a href="#ci_static_ctors">static constructor</a>
> into
> -every translation unit that includes it.</p>
> -
> -<p>Note that using the other stream headers (<tt><sstream></tt> for
> -example) is not problematic in this regard —
> -just <tt><iostream></tt>. However, <tt>raw_ostream</tt> provides
> various
> -APIs that are better performing for almost every use than
> <tt>std::ostream</tt>
> -style APIs. <b>Therefore new code should always
> -use <a href="#ll_raw_ostream"><tt>raw_ostream</tt></a> for writing, or
> -the <tt>llvm::MemoryBuffer</tt> API for reading files.</b></p>
> -
> -</div>
> -
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="ll_raw_ostream">Use <tt>raw_ostream</tt></a>
> -</h4>
> -
> -<div>
> -
> -<p>LLVM includes a lightweight, simple, and efficient stream
> implementation
> -in <tt>llvm/Support/raw_ostream.h</tt>, which provides all of the common
> -features of <tt>std::ostream</tt>.  All new code should use
> <tt>raw_ostream</tt>
> -instead of <tt>ostream</tt>.</p>
> -
> -<p>Unlike <tt>std::ostream</tt>, <tt>raw_ostream</tt> is not a template
> and can
> -be forward declared as <tt>class raw_ostream</tt>.  Public headers should
> -generally not include the <tt>raw_ostream</tt> header, but use forward
> -declarations and constant references to <tt>raw_ostream</tt>
> instances.</p>
> -
> -</div>
> -
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="ll_avoidendl">Avoid <tt>std::endl</tt></a>
> -</h4>
> -
> -<div>
> -
> -<p>The <tt>std::endl</tt> modifier, when used with <tt>iostreams</tt>
> outputs a
> -newline to the output stream specified.  In addition to doing this,
> however, it
> -also flushes the output stream.  In other words, these are equivalent:</p>
> -
> -<div class="doc_code">
> -<pre>
> -std::cout << std::endl;
> -std::cout << '\n' << std::flush;
> -</pre>
> -</div>
> -
> -<p>Most of the time, you probably have no reason to flush the output
> stream, so
> -it's better to use a literal <tt>'\n'</tt>.</p>
> -
> -</div>
> -
> -</div>
> -
> -<!--
> ======================================================================= -->
> -<h3>
> -  <a name="nano">Microscopic Details</a>
> -</h3>
> -<!--
> ======================================================================= -->
> -
> -<div>
> -
> -<p>This section describes preferred low-level formatting guidelines along
> with
> -reasoning on why we prefer them.</p>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="micro_spaceparen">Spaces Before Parentheses</a>
> -</h4>
> -
> -<div>
> -
> -<p>We prefer to put a space before an open parenthesis only in control
> flow
> -statements, but not in normal function call expressions and function-like
> -macros.  For example, this is good:</p>
> -
> -<div class="doc_code">
> -<pre>
> -<b>if (</b>x) ...
> -<b>for (</b>i = 0; i != 100; ++i) ...
> -<b>while (</b>llvm_rocks) ...
> -
> -<b>somefunc(</b>42);
> -<b><a href="#ll_assert">assert</a>(</b>3 != 4 && "laws of math
> are failing me");
> -
> -a = <b>foo(</b>42, 92) + <b>bar(</b>x);
> -</pre>
> -</div>
> -
> -<p>and this is bad:</p>
> -
> -<div class="doc_code">
> -<pre>
> -<b>if(</b>x) ...
> -<b>for(</b>i = 0; i != 100; ++i) ...
> -<b>while(</b>llvm_rocks) ...
> -
> -<b>somefunc (</b>42);
> -<b><a href="#ll_assert">assert</a> (</b>3 != 4 && "laws of math
> are failing me");
> -
> -a = <b>foo (</b>42, 92) + <b>bar (</b>x);
> -</pre>
> -</div>
> -
> -<p>The reason for doing this is not completely arbitrary.  This style
> makes
> -control flow operators stand out more, and makes expressions flow better.
> The
> -function call operator binds very tightly as a postfix operator.  Putting
> a
> -space after a function name (as in the last example) makes it appear that
> the
> -code might bind the arguments of the left-hand-side of a binary operator
> with
> -the argument list of a function and the name of the right side.  More
> -specifically, it is easy to misread the "a" example as:</p>
> -
> -<div class="doc_code">
> -<pre>
> -a = foo <b>(</b>(42, 92) + bar<b>)</b> (x);
> -</pre>
> -</div>
> -
> -<p>when skimming through the code.  By avoiding a space in a function, we
> avoid
> -this misinterpretation.</p>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="micro_preincrement">Prefer Preincrement</a>
> -</h4>
> -
> -<div>
> -
> -<p>Hard fast rule: Preincrement (<tt>++X</tt>) may be no slower than
> -postincrement (<tt>X++</tt>) and could very well be a lot faster than it.
>  Use
> -preincrementation whenever possible.</p>
> -
> -<p>The semantics of postincrement include making a copy of the value being
> -incremented, returning it, and then preincrementing the "work value".  For
> -primitive types, this isn't a big deal... but for iterators, it can be a
> huge
> -issue (for example, some iterators contains stack and set objects in
> them...
> -copying an iterator could invoke the copy ctor's of these as well).  In
> general,
> -get in the habit of always using preincrement, and you won't have a
> problem.</p>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="micro_namespaceindent">Namespace Indentation</a>
> -</h4>
> -
> -<div>
> -
> -<p>
> -In general, we strive to reduce indentation wherever possible.  This is
> useful
> -because we want code to <a href="#scf_codewidth">fit into 80 columns</a>
> without
> -wrapping horribly, but also because it makes it easier to understand the
> code.
> -Namespaces are a funny thing: they are often large, and we often desire
> to put
> -lots of stuff into them (so they can be large).  Other times they are
> tiny,
> -because they just hold an enum or something similar.  In order to balance
> this,
> -we use different approaches for small versus large namespaces.
> -</p>
> -
> -<p>
> -If a namespace definition is small and <em>easily</em> fits on a screen
> (say,
> -less than 35 lines of code), then you should indent its body.  Here's an
> -example:
> -</p>
> -
> -<div class="doc_code">
> -<pre>
> -namespace llvm {
> -  namespace X86 {
> -    /// RelocationType - An enum for the x86 relocation codes. Note that
> -    /// the terminology here doesn't follow x86 convention - word means
> -    /// 32-bit and dword means 64-bit.
> -    enum RelocationType {
> -      /// reloc_pcrel_word - PC relative relocation, add the relocated
> value to
> -      /// the value already in memory, after we adjust it for where the
> PC is.
> -      reloc_pcrel_word = 0,
> -
> -      /// reloc_picrel_word - PIC base relative relocation, add the
> relocated
> -      /// value to the value already in memory, after we adjust it for
> where the
> -      /// PIC base is.
> -      reloc_picrel_word = 1,
> -
> -      /// reloc_absolute_word, reloc_absolute_dword - Absolute
> relocation, just
> -      /// add the relocated value to the value already in memory.
> -      reloc_absolute_word = 2,
> -      reloc_absolute_dword = 3
> -    };
> -  }
> -}
> -</pre>
> -</div>
> -
> -<p>Since the body is small, indenting adds value because it makes it very
> clear
> -where the namespace starts and ends, and it is easy to take the whole
> thing in
> -in one "gulp" when reading the code.  If the blob of code in the
> namespace is
> -larger (as it typically is in a header in the <tt>llvm</tt> or
> <tt>clang</tt> namespaces), do not
> -indent the code, and add a comment indicating what namespace is being
> closed.
> -For example:</p>
> -
> -<div class="doc_code">
> -<pre>
> -namespace llvm {
> -namespace knowledge {
> -
> -/// Grokable - This class represents things that Smith can have an
> intimate
> -/// understanding of and contains the data associated with it.
> -class Grokable {
> -...
> -public:
> -  explicit Grokable() { ... }
> -  virtual ~Grokable() = 0;
> -
> -  ...
> -
> -};
> -
> -} // end namespace knowledge
> -} // end namespace llvm
> -</pre>
> -</div>
> -
> -<p>Because the class is large, we don't expect that the reader can easily
> -understand the entire concept in a glance, and the end of the file (where
> the
> -namespaces end) may be a long ways away from the place they open.  As
> such,
> -indenting the contents of the namespace doesn't add any value, and
> detracts from
> -the readability of the class.  In these cases it is best to <em>not</em>
> indent
> -the contents of the namespace.</p>
> -
> -</div>
> -
> -<!--
> _______________________________________________________________________ -->
> -<h4>
> -  <a name="micro_anonns">Anonymous Namespaces</a>
> -</h4>
> -
> -<div>
> -
> -<p>After talking about namespaces in general, you may be wondering about
> -anonymous namespaces in particular.
> -Anonymous namespaces are a great language feature that tells the C++
> compiler
> -that the contents of the namespace are only visible within the current
> -translation unit, allowing more aggressive optimization and eliminating
> the
> -possibility of symbol name collisions.  Anonymous namespaces are to C++ as
> -"static" is to C functions and global variables.  While "static" is
> available
> -in C++, anonymous namespaces are more general: they can make entire
> classes
> -private to a file.</p>
> -
> -<p>The problem with anonymous namespaces is that they naturally want to
> -encourage indentation of their body, and they reduce locality of
> reference: if
> -you see a random function definition in a C++ file, it is easy to see if
> it is
> -marked static, but seeing if it is in an anonymous namespace requires
> scanning
> -a big chunk of the file.</p>
> -
> -<p>Because of this, we have a simple guideline: make anonymous namespaces
> as
> -small as possible, and only use them for class declarations.  For
> example, this
> -is good:</p>
> -
> -<div class="doc_code">
> -<pre>
> -<b>namespace {</b>
> -  class StringSort {
> -  ...
> -  public:
> -    StringSort(...)
> -    bool operator<(const char *RHS) const;
> -  };
> -<b>} // end anonymous namespace</b>
> -
> -static void Helper() {
> -  ...
> -}
> -
> -bool StringSort::operator<(const char *RHS) const {
> -  ...
> -}
> -
> -</pre>
> -</div>
> -
> -<p>This is bad:</p>
> -
> -
> -<div class="doc_code">
> -<pre>
> -<b>namespace {</b>
> -class StringSort {
> -...
> -public:
> -  StringSort(...)
> -  bool operator<(const char *RHS) const;
> -};
> -
> -void Helper() {
> -  ...
> -}
> -
> -bool StringSort::operator<(const char *RHS) const {
> -  ...
> -}
> -
> -<b>} // end anonymous namespace</b>
> -
> -</pre>
> -</div>
> -
> -
> -<p>This is bad specifically because if you're looking at "Helper" in the
> middle
> -of a large C++ file, that you have no immediate way to tell if it is
> local to
> -the file.  When it is marked static explicitly, this is immediately
> obvious.
> -Also, there is no reason to enclose the definition of "operator<" in
> the
> -namespace just because it was declared there.
> -</p>
> -
> -</div>
> -
> -</div>
> -
> -</div>
> -
> -<!--
> *********************************************************************** -->
> -<h2>
> -  <a name="seealso">See Also</a>
> -</h2>
> -<!--
> *********************************************************************** -->
> -
> -<div>
> -
> -<p>A lot of these comments and recommendations have been culled for other
> -sources.  Two particularly important books for our work are:</p>
> -
> -<ol>
> -
> -<li><a href="
> http://www.amazon.com/Effective-Specific-Addison-Wesley-Professional-Computing/dp/0321334876
> ">Effective
> -C++</a> by Scott Meyers.  Also
> -interesting and useful are "More Effective C++" and "Effective STL" by
> the same
> -author.</li>
> -
> -<li>Large-Scale C++ Software Design by John Lakos</li>
> -
> -</ol>
> -
> -<p>If you get some free time, and you haven't read them: do so, you might
> learn
> -something.</p>
> -
> -</div>
> -
> -<!--
> *********************************************************************** -->
> -
> -<hr>
> -<address>
> -  <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
> -  src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid
> CSS"></a>
> -  <a href="http://validator.w3.org/check/referer"><img
> -  src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML
> 4.01"></a>
> -
> -  <a href="mailto:sabre at nondot.org">Chris Lattner</a><br>
> -  <a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
> -  Last modified: $Date$
> -</address>
> -
> -</body>
> -</html>
>
> Added: llvm/trunk/docs/CodingStandards.rst
> URL:
> http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/CodingStandards.rst?rev=158786&view=auto
>
> ==============================================================================
> --- llvm/trunk/docs/CodingStandards.rst (added)
> +++ llvm/trunk/docs/CodingStandards.rst Tue Jun 19 21:57:56 2012
> @@ -0,0 +1,1148 @@
> +.. _coding_standards:
> +
> +=====================
> +LLVM Coding Standards
> +=====================
> +
> +.. contents::
> +   :local:
> +
> +Introduction
> +============
> +
> +This document attempts to describe a few coding standards that are being
> used in
> +the LLVM source tree.  Although no coding standards should be regarded as
> +absolute requirements to be followed in all instances, coding standards
> are
> +particularly important for large-scale code bases that follow a
> library-based
> +design (like LLVM).
> +
> +This document intentionally does not prescribe fixed standards for
> religious
> +issues such as brace placement and space usage.  For issues like this,
> follow
> +the golden rule:
> +
> +.. _Golden Rule:
> +
> +    **If you are extending, enhancing, or bug fixing already implemented
> code,
> +    use the style that is already being used so that the source is
> uniform and
> +    easy to follow.**
> +
> +Note that some code bases (e.g. ``libc++``) have really good reasons to
> deviate
> +from the coding standards.  In the case of ``libc++``, this is because the
> +naming and other conventions are dictated by the C++ standard.  If you
> think
> +there is a specific good reason to deviate from the standards here,
> please bring
> +it up on the LLVMdev mailing list.
> +
> +There are some conventions that are not uniformly followed in the code
> base
> +(e.g. the naming convention).  This is because they are relatively new,
> and a
> +lot of code was written before they were put in place.  Our long term
> goal is
> +for the entire codebase to follow the convention, but we explicitly *do
> not*
> +want patches that do large-scale reformating of existing code.  On the
> other
> +hand, it is reasonable to rename the methods of a class if you're about to
> +change it in some other way.  Just do the reformating as a separate
> commit from
> +the functionality change.
> +
> +The ultimate goal of these guidelines is the increase readability and
> +maintainability of our common source base. If you have suggestions for
> topics to
> +be included, please mail them to `Chris <mailto:sabre at nondot.org>`_.
> +
> +Mechanical Source Issues
> +========================
> +
> +Source Code Formatting
> +----------------------
> +
> +Commenting
> +^^^^^^^^^^
> +
> +Comments are one critical part of readability and maintainability.
>  Everyone
> +knows they should comment their code, and so should you.  When writing
> comments,
> +write them as English prose, which means they should use proper
> capitalization,
> +punctuation, etc.  Aim to describe what the code is trying to do and why,
> not
> +*how* it does it at a micro level. Here are a few critical things to
> document:
> +
> +.. _header file comment:
> +
> +File Headers
> +""""""""""""
> +
> +Every source file should have a header on it that describes the basic
> purpose of
> +the file.  If a file does not have a header, it should not be checked
> into the
> +tree.  The standard header looks like this:
> +
> +.. code-block:: c++
> +
> +  //===-- llvm/Instruction.h - Instruction class definition -------*- C++
> -*-===//
> +  //
> +  //                     The LLVM Compiler Infrastructure
> +  //
> +  // This file is distributed under the University of Illinois Open Source
> +  // License. See LICENSE.TXT for details.
> +  //
> +
>  //===----------------------------------------------------------------------===//
> +  //
> +  // This file contains the declaration of the Instruction class, which
> is the
> +  // base class for all of the VM instructions.
> +  //
> +
>  //===----------------------------------------------------------------------===//
> +
> +A few things to note about this particular format: The "``-*- C++ -*-``"
> string
> +on the first line is there to tell Emacs that the source file is a C++
> file, not
> +a C file (Emacs assumes ``.h`` files are C files by default).
> +
> +.. note::
> +
> +    This tag is not necessary in ``.cpp`` files.  The name of the file is
> also
> +    on the first line, along with a very short description of the purpose
> of the
> +    file.  This is important when printing out code and flipping though
> lots of
> +    pages.
> +
> +The next section in the file is a concise note that defines the license
> that the
> +file is released under.  This makes it perfectly clear what terms the
> source
> +code can be distributed under and should not be modified in any way.
> +
> +The main body of the description does not have to be very long in most
> cases.
> +Here it's only two lines.  If an algorithm is being implemented or
> something
> +tricky is going on, a reference to the paper where it is published should
> be
> +included, as well as any notes or *gotchas* in the code to watch out for.
> +
> +Class overviews
> +"""""""""""""""
> +
> +Classes are one fundamental part of a good object oriented design.  As
> such, a
> +class definition should have a comment block that explains what the class
> is
> +used for and how it works.  Every non-trivial class is expected to have a
> +``doxygen`` comment block.
> +
> +Method information
> +""""""""""""""""""
> +
> +Methods defined in a class (as well as any global functions) should also
> be
> +documented properly.  A quick note about what it does and a description
> of the
> +borderline behaviour is all that is necessary here (unless something
> +particularly tricky or insidious is going on).  The hope is that people
> can
> +figure out how to use your interfaces without reading the code itself.
> +
> +Good things to talk about here are what happens when something unexpected
> +happens: does the method return null?  Abort?  Format your hard disk?
> +
> +Comment Formatting
> +^^^^^^^^^^^^^^^^^^
> +
> +In general, prefer C++ style (``//``) comments.  They take less space,
> require
> +less typing, don't have nesting problems, etc.  There are a few cases
> when it is
> +useful to use C style (``/* */``) comments however:
> +
> +#. When writing C code: Obviously if you are writing C code, use C style
> +   comments.
> +
> +#. When writing a header file that may be ``#include``\d by a C source
> file.
> +
> +#. When writing a source file that is used by a tool that only accepts C
> style
> +   comments.
> +
> +To comment out a large block of code, use ``#if 0`` and ``#endif``. These
> nest
> +properly and are better behaved in general than C style comments.
> +
> +``#include`` Style
> +^^^^^^^^^^^^^^^^^^
> +
> +Immediately after the `header file comment`_ (and include guards if
> working on a
> +header file), the `minimal list of #includes`_ required by the file
> should be
> +listed.  We prefer these ``#include``\s to be listed in this order:
> +
> +.. _Main Module Header:
> +.. _Local/Private Headers:
> +
> +#. Main Module Header
> +#. Local/Private Headers
> +#. ``llvm/*``
> +#. ``llvm/Analysis/*``
> +#. ``llvm/Assembly/*``
> +#. ``llvm/Bitcode/*``
> +#. ``llvm/CodeGen/*``
> +#. ...
> +#. ``llvm/Support/*``
> +#. ``llvm/Config/*``
> +#. System ``#include``\s
> +
> +and each category should be sorted by name.
> +
> +The `Main Module Header`_ file applies to ``.cpp`` files which implement
> an
> +interface defined by a ``.h`` file.  This ``#include`` should always be
> included
> +**first** regardless of where it lives on the file system.  By including a
> +header file first in the ``.cpp`` files that implement the interfaces, we
> ensure
> +that the header does not have any hidden dependencies which are not
> explicitly
> +``#include``\d in the header, but should be. It is also a form of
> documentation
> +in the ``.cpp`` file to indicate where the interfaces it implements are
> defined.
> +
> +.. _fit into 80 columns:
> +
> +Source Code Width
> +^^^^^^^^^^^^^^^^^
> +
> +Write your code to fit within 80 columns of text.  This helps those of us
> who
> +like to print out code and look at your code in an ``xterm`` without
> resizing
> +it.
> +
> +The longer answer is that there must be some limit to the width of the
> code in
> +order to reasonably allow developers to have multiple files side-by-side
> in
> +windows on a modest display.  If you are going to pick a width limit, it
> is
> +somewhat arbitrary but you might as well pick something standard.  Going
> with 90
> +columns (for example) instead of 80 columns wouldn't add any significant
> value
> +and would be detrimental to printing out code.  Also many other projects
> have
> +standardized on 80 columns, so some people have already configured their
> editors
> +for it (vs something else, like 90 columns).
> +
> +This is one of many contentious issues in coding standards, but it is not
> up for
> +debate.
> +
> +Use Spaces Instead of Tabs
> +^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +In all cases, prefer spaces to tabs in source files.  People have
> different
> +preferred indentation levels, and different styles of indentation that
> they
> +like; this is fine.  What isn't fine is that different editors/viewers
> expand
> +tabs out to different tab stops.  This can cause your code to look
> completely
> +unreadable, and it is not worth dealing with.
> +
> +As always, follow the `Golden Rule`_ above: follow the style of
> +existing code if you are modifying and extending it.  If you like four
> spaces of
> +indentation, **DO NOT** do that in the middle of a chunk of code with two
> spaces
> +of indentation.  Also, do not reindent a whole source file: it makes for
> +incredible diffs that are absolutely worthless.
> +
> +Indent Code Consistently
> +^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Okay, in your first year of programming you were told that indentation is
> +important.  If you didn't believe and internalize this then, now is the
> time.
> +Just do it.
> +
> +Compiler Issues
> +---------------
> +
> +Treat Compiler Warnings Like Errors
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +If your code has compiler warnings in it, something is wrong --- you
> aren't
> +casting values correctly, you have "questionable" constructs in your
> code, or
> +you are doing something legitimately wrong.  Compiler warnings can cover
> up
> +legitimate errors in output and make dealing with a translation unit
> difficult.
> +
> +It is not possible to prevent all warnings from all compilers, nor is it
> +desirable.  Instead, pick a standard compiler (like ``gcc``) that
> provides a
> +good thorough set of warnings, and stick to it.  At least in the case of
> +``gcc``, it is possible to work around any spurious errors by changing the
> +syntax of the code slightly.  For example, a warning that annoys me
> occurs when
> +I write code like this:
> +
> +.. code-block:: c++
> +
> +  if (V = getValue()) {
> +    ...
> +  }
> +
> +``gcc`` will warn me that I probably want to use the ``==`` operator, and
> that I
> +probably mistyped it.  In most cases, I haven't, and I really don't want
> the
> +spurious errors.  To fix this particular problem, I rewrite the code like
> +this:
> +
> +.. code-block:: c++
> +
> +  if ((V = getValue())) {
> +    ...
> +  }
> +
> +which shuts ``gcc`` up.  Any ``gcc`` warning that annoys you can be fixed
> by
> +massaging the code appropriately.
> +
> +Write Portable Code
> +^^^^^^^^^^^^^^^^^^^
> +
> +In almost all cases, it is possible and within reason to write completely
> +portable code.  If there are cases where it isn't possible to write
> portable
> +code, isolate it behind a well defined (and well documented) interface.
> +
> +In practice, this means that you shouldn't assume much about the host
> compiler
> +(and Visual Studio tends to be the lowest common denominator).  If
> advanced
> +features are used, they should only be an implementation detail of a
> library
> +which has a simple exposed API, and preferably be buried in ``libSystem``.
> +
> +Do not use RTTI or Exceptions
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +In an effort to reduce code and executable size, LLVM does not use RTTI
> +(e.g. ``dynamic_cast<>;``) or exceptions.  These two language features
> violate
> +the general C++ principle of *"you only pay for what you use"*, causing
> +executable bloat even if exceptions are never used in the code base, or
> if RTTI
> +is never used for a class.  Because of this, we turn them off globally in
> the
> +code.
> +
> +That said, LLVM does make extensive use of a hand-rolled form of RTTI
> that use
> +templates like `isa<>, cast<>, and dyn_cast<>
> <ProgrammersManual.html#isa>`_.
> +This form of RTTI is opt-in and can be added to any class.  It is also
> +substantially more efficient than ``dynamic_cast<>``.
> +
> +.. _static constructor:
> +
> +Do not use Static Constructors
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Static constructors and destructors (e.g. global variables whose types
> have a
> +constructor or destructor) should not be added to the code base, and
> should be
> +removed wherever possible.  Besides `well known problems
> +<http://yosefk.com/c++fqa/ctors.html#fqa-10.12>`_ where the order of
> +initialization is undefined between globals in different source files, the
> +entire concept of static constructors is at odds with the common use case
> of
> +LLVM as a library linked into a larger application.
> +
> +Consider the use of LLVM as a JIT linked into another application
> (perhaps for
> +`OpenGL, custom languages <http://llvm.org/Users.html>`_, `shaders in
> movies
> +<http://llvm.org/devmtg/2010-11/Gritz-OpenShadingLang.pdf>`_, etc). Due
> to the
> +design of static constructors, they must be executed at startup time of
> the
> +entire application, regardless of whether or how LLVM is used in that
> larger
> +application.  There are two problems with this:
> +
> +* The time to run the static constructors impacts startup time of
> applications
> +  --- a critical time for GUI apps, among others.
> +
> +* The static constructors cause the app to pull many extra pages of
> memory off
> +  the disk: both the code for the constructor in each ``.o`` file and the
> small
> +  amount of data that gets touched. In addition, touched/dirty pages put
> more
> +  pressure on the VM system on low-memory machines.
> +
> +We would really like for there to be zero cost for linking in an
> additional LLVM
> +target or other library into an application, but static constructors
> violate
> +this goal.
> +
> +That said, LLVM unfortunately does contain static constructors.  It would
> be a
> +`great project <http://llvm.org/PR11944>`_ for someone to purge all
> static
> +constructors from LLVM, and then enable the ``-Wglobal-constructors``
> warning
> +flag (when building with Clang) to ensure we do not regress in the future.
> +
> +Use of ``class`` and ``struct`` Keywords
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +In C++, the ``class`` and ``struct`` keywords can be used almost
> +interchangeably. The only difference is when they are used to declare a
> class:
> +``class`` makes all members private by default while ``struct`` makes all
> +members public by default.
> +
> +Unfortunately, not all compilers follow the rules and some will generate
> +different symbols based on whether ``class`` or ``struct`` was used to
> declare
> +the symbol.  This can lead to problems at link time.
> +
> +So, the rule for LLVM is to always use the ``class`` keyword, unless
> **all**
> +members are public and the type is a C++ `POD
> +<http://en.wikipedia.org/wiki/Plain_old_data_structure>`_ type, in which
> case
> +``struct`` is allowed.
> +
> +Style Issues
> +============
> +
> +The High-Level Issues
> +---------------------
> +
> +A Public Header File **is** a Module
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +C++ doesn't do too well in the modularity department.  There is no real
> +encapsulation or data hiding (unless you use expensive protocol classes),
> but it
> +is what we have to work with.  When you write a public header file (in
> the LLVM
> +source tree, they live in the top level "``include``" directory), you are
> +defining a module of functionality.
> +
> +Ideally, modules should be completely independent of each other, and their
> +header files should only ``#include`` the absolute minimum number of
> headers
> +possible. A module is not just a class, a function, or a namespace: it's a
> +collection of these that defines an interface.  This interface may be
> several
> +functions, classes, or data structures, but the important issue is how
> they work
> +together.
> +
> +In general, a module should be implemented by one or more ``.cpp`` files.
>  Each
> +of these ``.cpp`` files should include the header that defines their
> interface
> +first.  This ensures that all of the dependences of the module header
> have been
> +properly added to the module header itself, and are not implicit.  System
> +headers should be included after user headers for a translation unit.
> +
> +.. _minimal list of #includes:
> +
> +``#include`` as Little as Possible
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +``#include`` hurts compile time performance.  Don't do it unless you have
> to,
> +especially in header files.
> +
> +But wait! Sometimes you need to have the definition of a class to use it,
> or to
> +inherit from it.  In these cases go ahead and ``#include`` that header
> file.  Be
> +aware however that there are many cases where you don't need to have the
> full
> +definition of a class.  If you are using a pointer or reference to a
> class, you
> +don't need the header file.  If you are simply returning a class instance
> from a
> +prototyped function or method, you don't need it.  In fact, for most
> cases, you
> +simply don't need the definition of a class. And not ``#include``\ing
> speeds up
> +compilation.
> +
> +It is easy to try to go too overboard on this recommendation, however.
>  You
> +**must** include all of the header files that you are using --- you can
> include
> +them either directly or indirectly through another header file.  To make
> sure
> +that you don't accidentally forget to include a header file in your module
> +header, make sure to include your module header **first** in the
> implementation
> +file (as mentioned above).  This way there won't be any hidden
> dependencies that
> +you'll find out about later.
> +
> +Keep "Internal" Headers Private
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Many modules have a complex implementation that causes them to use more
> than one
> +implementation (``.cpp``) file.  It is often tempting to put the internal
> +communication interface (helper classes, extra functions, etc) in the
> public
> +module header file.  Don't do this!
> +
> +If you really need to do something like this, put a private header file
> in the
> +same directory as the source files, and include it locally.  This ensures
> that
> +your private interface remains private and undisturbed by outsiders.
> +
> +.. note::
> +
> +    It's okay to put extra implementation methods in a public class
> itself. Just
> +    make them private (or protected) and all is well.
> +
> +.. _early exits:
> +
> +Use Early Exits and ``continue`` to Simplify Code
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +When reading code, keep in mind how much state and how many previous
> decisions
> +have to be remembered by the reader to understand a block of code.  Aim to
> +reduce indentation where possible when it doesn't make it more difficult
> to
> +understand the code.  One great way to do this is by making use of early
> exits
> +and the ``continue`` keyword in long loops.  As an example of using an
> early
> +exit from a function, consider this "bad" code:
> +
> +.. code-block:: c++
> +
> +  Value *DoSomething(Instruction *I) {
> +    if (!isa<TerminatorInst>(I) &&
> +        I->hasOneUse() && SomeOtherThing(I)) {
> +      ... some long code ....
> +    }
> +
> +    return 0;
> +  }
> +
> +This code has several problems if the body of the ``'if'`` is large.  When
> +you're looking at the top of the function, it isn't immediately clear
> that this
> +*only* does interesting things with non-terminator instructions, and only
> +applies to things with the other predicates.  Second, it is relatively
> difficult
> +to describe (in comments) why these predicates are important because the
> ``if``
> +statement makes it difficult to lay out the comments.  Third, when you're
> deep
> +within the body of the code, it is indented an extra level.  Finally, when
> +reading the top of the function, it isn't clear what the result is if the
> +predicate isn't true; you have to read to the end of the function to know
> that
> +it returns null.
> +
> +It is much preferred to format the code like this:
> +
> +.. code-block:: c++
> +
> +  Value *DoSomething(Instruction *I) {
> +    // Terminators never need 'something' done to them because ...
> +    if (isa<TerminatorInst>(I))
> +      return 0;
> +
> +    // We conservatively avoid transforming instructions with multiple
> uses
> +    // because goats like cheese.
> +    if (!I->hasOneUse())
> +      return 0;
> +
> +    // This is really just here for example.
> +    if (!SomeOtherThing(I))
> +      return 0;
> +
> +    ... some long code ....
> +  }
> +
> +This fixes these problems.  A similar problem frequently happens in
> ``for``
> +loops.  A silly example is something like this:
> +
> +.. code-block:: c++
> +
> +  for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II != E;
> ++II) {
> +    if (BinaryOperator *BO = dyn_cast<BinaryOperator>(II)) {
> +      Value *LHS = BO->getOperand(0);
> +      Value *RHS = BO->getOperand(1);
> +      if (LHS != RHS) {
> +        ...
> +      }
> +    }
> +  }
> +
> +When you have very, very small loops, this sort of structure is fine. But
> if it
> +exceeds more than 10-15 lines, it becomes difficult for people to read and
> +understand at a glance. The problem with this sort of code is that it
> gets very
> +nested very quickly. Meaning that the reader of the code has to keep a
> lot of
> +context in their brain to remember what is going immediately on in the
> loop,
> +because they don't know if/when the ``if`` conditions will have
> ``else``\s etc.
> +It is strongly preferred to structure the loop like this:
> +
> +.. code-block:: c++
> +
> +  for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II != E;
> ++II) {
> +    BinaryOperator *BO = dyn_cast<BinaryOperator>(II);
> +    if (!BO) continue;
> +
> +    Value *LHS = BO->getOperand(0);
> +    Value *RHS = BO->getOperand(1);
> +    if (LHS == RHS) continue;
> +
> +    ...
> +  }
> +
> +This has all the benefits of using early exits for functions: it reduces
> nesting
> +of the loop, it makes it easier to describe why the conditions are true,
> and it
> +makes it obvious to the reader that there is no ``else`` coming up that
> they
> +have to push context into their brain for.  If a loop is large, this can
> be a
> +big understandability win.
> +
> +Don't use ``else`` after a ``return``
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +For similar reasons above (reduction of indentation and easier reading),
> please
> +do not use ``'else'`` or ``'else if'`` after something that interrupts
> control
> +flow --- like ``return``, ``break``, ``continue``, ``goto``, etc. For
> +example, this is *bad*:
> +
> +.. code-block:: c++
> +
> +  case 'J': {
> +    if (Signed) {
> +      Type = Context.getsigjmp_bufType();
> +      if (Type.isNull()) {
> +        Error = ASTContext::GE_Missing_sigjmp_buf;
> +        return QualType();
> +      } else {
> +        break;
> +      }
> +    } else {
> +      Type = Context.getjmp_bufType();
> +      if (Type.isNull()) {
> +        Error = ASTContext::GE_Missing_jmp_buf;
> +        return QualType();
> +      <b>} else {
> +        break;
> +      }</b>
> +    }
> +  }
> +  }
> +
> +It is better to write it like this:
> +
> +.. code-block:: c++
> +
> +  case 'J':
> +    if (Signed) {
> +      Type = Context.getsigjmp_bufType();
> +      if (Type.isNull()) {
> +        Error = ASTContext::GE_Missing_sigjmp_buf;
> +        return QualType();
> +      }
> +    } else {
> +      Type = Context.getjmp_bufType();
> +      if (Type.isNull()) {
> +        Error = ASTContext::GE_Missing_jmp_buf;
> +        return QualType();
> +      }
> +    }
> +    break;
> +
> +Or better yet (in this case) as:
> +
> +.. code-block:: c++
> +
> +  case 'J':
> +    if (Signed)
> +      Type = Context.getsigjmp_bufType();
> +    else
> +      Type = Context.getjmp_bufType();
> +
> +    if (Type.isNull()) {
> +      Error = Signed ? ASTContext::GE_Missing_sigjmp_buf :
> +                       ASTContext::GE_Missing_jmp_buf;
> +      return QualType();
> +    }
> +    break;
> +
> +The idea is to reduce indentation and the amount of code you have to keep
> track
> +of when reading the code.
> +
> +Turn Predicate Loops into Predicate Functions
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +It is very common to write small loops that just compute a boolean value.
>  There
> +are a number of ways that people commonly write these, but an example of
> this
> +sort of thing is:
> +
> +.. code-block:: c++
> +
> +  bool FoundFoo = false;
> +  for (unsigned i = 0, e = BarList.size(); i != e; ++i)
> +    if (BarList[i]->isFoo()) {
> +      FoundFoo = true;
> +      break;
> +    }
> +
> +  if (FoundFoo) {
> +    ...
> +  }
> +
> +This sort of code is awkward to write, and is almost always a bad sign.
>  Instead
> +of this sort of loop, we strongly prefer to use a predicate function
> (which may
> +be `static`_) that uses `early exits`_ to compute the predicate.  We
> prefer the
> +code to be structured like this:
> +
> +.. code-block:: c++
> +
> +  /// ListContainsFoo - Return true if the specified list has an element
> that is
> +  /// a foo.
> +  static bool ListContainsFoo(const std::vector<Bar*> &List) {
> +    for (unsigned i = 0, e = List.size(); i != e; ++i)
> +      if (List[i]->isFoo())
> +        return true;
> +    return false;
> +  }
> +  ...
> +
> +  if (ListContainsFoo(BarList)) {
> +    ...
> +  }
> +
> +There are many reasons for doing this: it reduces indentation and factors
> out
> +code which can often be shared by other code that checks for the same
> predicate.
> +More importantly, it *forces you to pick a name* for the function, and
> forces
> +you to write a comment for it.  In this silly example, this doesn't add
> much
> +value.  However, if the condition is complex, this can make it a lot
> easier for
> +the reader to understand the code that queries for this predicate.
>  Instead of
> +being faced with the in-line details of how we check to see if the BarList
> +contains a foo, we can trust the function name and continue reading with
> better
> +locality.
> +
> +The Low-Level Issues
> +--------------------
> +
> +Name Types, Functions, Variables, and Enumerators Properly
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Poorly-chosen names can mislead the reader and cause bugs. We cannot
> stress
> +enough how important it is to use *descriptive* names.  Pick names that
> match
> +the semantics and role of the underlying entities, within reason.  Avoid
> +abbreviations unless they are well known.  After picking a good name,
> make sure
> +to use consistent capitalization for the name, as inconsistency requires
> clients
> +to either memorize the APIs or to look it up to find the exact spelling.
> +
> +In general, names should be in camel case (e.g. ``TextFileReader`` and
> +``isLValue()``).  Different kinds of declarations have different rules:
> +
> +* **Type names** (including classes, structs, enums, typedefs, etc)
> should be
> +  nouns and start with an upper-case letter (e.g. ``TextFileReader``).
> +
> +* **Variable names** should be nouns (as they represent state).  The name
> should
> +  be camel case, and start with an upper case letter (e.g. ``Leader`` or
> +  ``Boats``).
> +
> +* **Function names** should be verb phrases (as they represent actions),
> and
> +  command-like function should be imperative.  The name should be camel
> case,
> +  and start with a lower case letter (e.g. ``openFile()`` or ``isFoo()``).
> +
> +* **Enum declarations** (e.g. ``enum Foo {...}``) are types, so they
> should
> +  follow the naming conventions for types.  A common use for enums is as a
> +  discriminator for a union, or an indicator of a subclass.  When an enum
> is
> +  used for something like this, it should have a ``Kind`` suffix
> +  (e.g. ``ValueKind``).
> +
> +* **Enumerators** (e.g. ``enum { Foo, Bar }``) 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,
> +  enumerators should have a prefix corresponding to the enum declaration
> name.
> +  For example, ``enum ValueKind { ... };`` may contain enumerators like
> +  ``VK_Argument``, ``VK_BasicBlock``, etc.  Enumerators that are just
> +  convenience constants are exempt from the requirement for a prefix.  For
> +  instance:
> +
> +  .. code-block:: c++
> +
> +      enum {
> +        MaxSize = 42,
> +        Density = 12
> +      };
> +
> +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. ``begin()``,
> +``push_back()``, and ``empty()``).
> +
> +Here are some examples of good and bad names:
> +
> +.. code-block::c++
> +
> +  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.
> +    ...
> +  }
> +
> +Assert Liberally
> +^^^^^^^^^^^^^^^^
> +
> +Use the "``assert``" macro to its fullest.  Check all of your
> preconditions and
> +assumptions, you never know when a bug (not necessarily even yours) might
> be
> +caught early by an assertion, which reduces debugging time dramatically.
>  The
> +"``<cassert>``" header file is probably already included by the header
> files you
> +are using, so it doesn't cost anything to use it.
> +
> +To further assist with debugging, make sure to put some kind of error
> message in
> +the assertion statement, which is printed if the assertion is tripped.
> This
> +helps the poor debugger make sense of why an assertion is being made and
> +enforced, and hopefully what to do about it.  Here is one complete
> example:
> +
> +.. code-block:: c++
> +
> +  inline Value *getOperand(unsigned i) {
> +    assert(i < Operands.size() && "getOperand() out of range!");
> +    return Operands[i];
> +  }
> +
> +Here are more examples:
> +
> +.. code-block:: c++
> +
> +  assert(Ty->isPointerType() && "Can't allocate a non pointer type!");
> +
> +  assert((Opcode == Shl || Opcode == Shr) && "ShiftInst Opcode invalid!");
> +
> +  assert(idx < getNumSuccessors() && "Successor # out of range!");
> +
> +  assert(V1.getType() == V2.getType() && "Constant types must be
> identical!");
> +
> +  assert(isa<PHINode>(Succ->front()) && "Only works on PHId BBs!");
> +
> +You get the idea.
> +
> +Please be aware that, when adding assert statements, not all compilers
> are aware
> +of the semantics of the assert.  In some places, asserts are used to
> indicate a
> +piece of code that should not be reached.  These are typically of the
> form:
> +
> +.. code-block:: c++
> +
> +  assert(0 && "Some helpful error message");
> +
> +When used in a function that returns a value, they should be followed
> with a
> +return statement and a comment indicating that this line is never
> reached.  This
> +will prevent a compiler which is unable to deduce that the assert
> statement
> +never returns from generating a warning.
> +
> +.. code-block:: c++
> +
> +  assert(0 && "Some helpful error message");
> +  return 0;
> +
> +Another issue is that values used only by assertions will produce an
> "unused
> +value" warning when assertions are disabled.  For example, this code will
> warn:
> +
> +.. code-block:: c++
> +
> +  unsigned Size = V.size();
> +  assert(Size > 42 && "Vector smaller than it should be");
> +
> +  bool NewToSet = Myset.insert(Value);
> +  assert(NewToSet && "The value shouldn't be in the set yet");
> +
> +These are two interesting different cases. In the first case, the call to
> +``V.size()`` is only useful for the assert, and we don't want it executed
> when
> +assertions are disabled.  Code like this should move the call into the
> assert
> +itself.  In the second case, the side effects of the call must happen
> whether
> +the assert is enabled or not.  In this case, the value should be cast to
> void to
> +disable the warning.  To be specific, it is preferred to write the code
> like
> +this:
> +
> +.. code-block:: c++
> +
> +  assert(V.size() > 42 && "Vector smaller than it should be");
> +
> +  bool NewToSet = Myset.insert(Value); (void)NewToSet;
> +  assert(NewToSet && "The value shouldn't be in the set yet");
> +
> +Do Not Use ``using namespace std``
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +In LLVM, we prefer to explicitly prefix all identifiers from the standard
> +namespace with an "``std::``" prefix, rather than rely on "``using
> namespace
> +std;``".
> +
> +In header files, adding a ``'using namespace XXX'`` directive pollutes the
> +namespace of any source file that ``#include``\s the header.  This is
> clearly a
> +bad thing.
> +
> +In implementation files (e.g. ``.cpp`` files), the rule is more of a
> stylistic
> +rule, but is still important.  Basically, using explicit namespace
> prefixes
> +makes the code **clearer**, because it is immediately obvious what
> facilities
> +are being used and where they are coming from. And **more portable**,
> because
> +namespace clashes cannot occur between LLVM code and other namespaces.
>  The
> +portability rule is important because different standard library
> implementations
> +expose different symbols (potentially ones they shouldn't), and future
> revisions
> +to the C++ standard will add more symbols to the ``std`` namespace.  As
> such, we
> +never use ``'using namespace std;'`` in LLVM.
> +
> +The exception to the general rule (i.e. it's not an exception for the
> ``std``
> +namespace) is for implementation files.  For example, all of the code in
> the
> +LLVM project implements code that lives in the 'llvm' namespace.  As
> such, it is
> +ok, and actually clearer, for the ``.cpp`` files to have a ``'using
> namespace
> +llvm;'`` directive at the top, after the ``#include``\s.  This reduces
> +indentation in the body of the file for source editors that indent based
> on
> +braces, and keeps the conceptual context cleaner.  The general form of
> this rule
> +is that any ``.cpp`` file that implements code in any namespace may use
> that
> +namespace (and its parents'), but should not use any others.
> +
> +Provide a Virtual Method Anchor for Classes in Headers
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +If a class is defined in a header file and has a vtable (either it has
> virtual
> +methods or it derives from classes with virtual methods), it must always
> have at
> +least one out-of-line virtual method in the class.  Without this, the
> compiler
> +will copy the vtable and RTTI into every ``.o`` file that ``#include``\s
> the
> +header, bloating ``.o`` file sizes and increasing link times.
> +
> +Don't evaluate ``end()`` every time through a loop
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +Because C++ doesn't have a standard "``foreach``" loop (though it can be
> +emulated with macros and may be coming in C++'0x) we end up writing a lot
> of
> +loops that manually iterate from begin to end on a variety of containers
> or
> +through other data structures.  One common mistake is to write a loop in
> this
> +style:
> +
> +.. code-block:: c++
> +
> +  BasicBlock *BB = ...
> +  for (BasicBlock::iterator I = BB->begin(); I != BB->end(); ++I)
> +    ... use I ...
> +
> +The problem with this construct is that it evaluates "``BB->end()``"
> every time
> +through the loop.  Instead of writing the loop like this, we strongly
> prefer
> +loops to be written so that they evaluate it once before the loop starts.
>  A
> +convenient way to do this is like so:
> +
> +.. code-block:: c++
> +
> +  BasicBlock *BB = ...
> +  for (BasicBlock::iterator I = BB->begin(), E = BB->end(); I != E; ++I)
> +    ... use I ...
> +
> +The observant may quickly point out that these two loops may have
> different
> +semantics: if the container (a basic block in this case) is being
> mutated, then
> +"``BB->end()``" may change its value every time through the loop and the
> second
> +loop may not in fact be correct.  If you actually do depend on this
> behavior,
> +please write the loop in the first form and add a comment indicating that
> you
> +did it intentionally.
> +
> +Why do we prefer the second form (when correct)?  Writing the loop in the
> first
> +form has two problems. First it may be less efficient than evaluating it
> at the
> +start of the loop.  In this case, the cost is probably minor --- a few
> extra
> +loads every time through the loop.  However, if the base expression is
> more
> +complex, then the cost can rise quickly.  I've seen loops where the end
> +expression was actually something like: "``SomeMap[x]->end()``" and map
> lookups
> +really aren't cheap.  By writing it in the second form consistently, you
> +eliminate the issue entirely and don't even have to think about it.
> +
> +The second (even bigger) issue is that writing the loop in the first form
> hints
> +to the reader that the loop is mutating the container (a fact that a
> comment
> +would handily confirm!).  If you write the loop in the second form, it is
> +immediately obvious without even looking at the body of the loop that the
> +container isn't being modified, which makes it easier to read the code and
> +understand what it does.
> +
> +While the second form of the loop is a few extra keystrokes, we do
> strongly
> +prefer it.
> +
> +``#include <iostream>`` is Forbidden
> +^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +The use of ``#include <iostream>`` in library files is hereby
> **forbidden**,
> +because many common implementations transparently inject a `static
> constructor`_
> +into every translation unit that includes it.
> +
> +Note that using the other stream headers (``<sstream>`` for example) is
> not
> +problematic in this regard --- just ``<iostream>``. However,
> ``raw_ostream``
> +provides various APIs that are better performing for almost every use than
> +``std::ostream`` style APIs.
> +
> +.. note::
> +
> +  New code should always use `raw_ostream`_ for writing, or the
> +  ``llvm::MemoryBuffer`` API for reading files.
> +
> +.. _raw_ostream:
> +
> +Use ``raw_ostream``
> +^^^^^^^^^^^^^^^^^^^
> +
> +LLVM includes a lightweight, simple, and efficient stream implementation
> in
> +``llvm/Support/raw_ostream.h``, which provides all of the common features
> of
> +``std::ostream``.  All new code should use ``raw_ostream`` instead of
> +``ostream``.
> +
> +Unlike ``std::ostream``, ``raw_ostream`` is not a template and can be
> forward
> +declared as ``class raw_ostream``.  Public headers should generally not
> include
> +the ``raw_ostream`` header, but use forward declarations and constant
> references
> +to ``raw_ostream`` instances.
> +
> +Avoid ``std::endl``
> +^^^^^^^^^^^^^^^^^^^
> +
> +The ``std::endl`` modifier, when used with ``iostreams`` outputs a
> newline to
> +the output stream specified.  In addition to doing this, however, it also
> +flushes the output stream.  In other words, these are equivalent:
> +
> +.. code-block:: c++
> +
> +  std::cout << std::endl;
> +  std::cout << '\n' << std::flush;
> +
> +Most of the time, you probably have no reason to flush the output stream,
> so
> +it's better to use a literal ``'\n'``.
> +
> +Microscopic Details
> +-------------------
> +
> +This section describes preferred low-level formatting guidelines along
> with
> +reasoning on why we prefer them.
> +
> +Spaces Before Parentheses
> +^^^^^^^^^^^^^^^^^^^^^^^^^
> +
> +We prefer to put a space before an open parenthesis only in control flow
> +statements, but not in normal function call expressions and function-like
> +macros.  For example, this is good:
> +
> +.. code-block:: c++
> +
> +  if (x) ...
> +  for (i = 0; i != 100; ++i) ...
> +  while (llvm_rocks) ...
> +
> +  somefunc(42);
> +  assert(3 != 4 && "laws of math are failing me");
> +
> +  a = foo(42, 92) + bar(x);
> +
> +and this is bad:
> +
> +.. code-block:: c++
> +
> +  if(x) ...
> +  for(i = 0; i != 100; ++i) ...
> +  while(llvm_rocks) ...
> +
> +  somefunc (42);
> +  assert (3 != 4 && "laws of math are failing me");
> +
> +  a = foo (42, 92) + bar (x);
> +
> +The reason for doing this is not completely arbitrary.  This style makes
> control
> +flow operators stand out more, and makes expressions flow better. The
> function
> +call operator binds very tightly as a postfix operator.  Putting a space
> after a
> +function name (as in the last example) makes it appear that the code
> might bind
> +the arguments of the left-hand-side of a binary operator with the
> argument list
> +of a function and the name of the right side.  More specifically, it is
> easy to
> +misread the "``a``" example as:
> +
> +.. code-block:: c++
> +
> +  a = foo ((42, 92) + bar) (x);
> +
> +when skimming through the code.  By avoiding a space in a function, we
> avoid
> +this misinterpretation.
> +
> +Prefer Preincrement
> +^^^^^^^^^^^^^^^^^^^
> +
> +Hard fast rule: Preincrement (``++X``) may be no slower than postincrement
> +(``X++``) and could very well be a lot faster than it.  Use
> preincrementation
> +whenever possible.
> +
> +The semantics of postincrement include making a copy of the value being
> +incremented, returning it, and then preincrementing the "work value".  For
> +primitive types, this isn't a big deal. But for iterators, it can be a
> huge
> +issue (for example, some iterators contains stack and set objects in
> them...
> +copying an iterator could invoke the copy ctor's of these as well).  In
> general,
> +get in the habit of always using preincrement, and you won't have a
> problem.
> +
> +
> +Namespace Indentation
> +^^^^^^^^^^^^^^^^^^^^^
> +
> +In general, we strive to reduce indentation wherever possible.  This is
> useful
> +because we want code to `fit into 80 columns`_ without wrapping horribly,
> but
> +also because it makes it easier to understand the code.  Namespaces are a
> funny
> +thing: they are often large, and we often desire to put lots of stuff
> into them
> +(so they can be large).  Other times they are tiny, because they just
> hold an
> +enum or something similar.  In order to balance this, we use different
> +approaches for small versus large namespaces.
> +
> +If a namespace definition is small and *easily* fits on a screen (say,
> less than
> +35 lines of code), then you should indent its body.  Here's an example:
> +
> +.. code-block:: c++
> +
> +  namespace llvm {
> +    namespace X86 {
> +      /// RelocationType - An enum for the x86 relocation codes. Note that
> +      /// the terminology here doesn't follow x86 convention - word means
> +      /// 32-bit and dword means 64-bit.
> +      enum RelocationType {
> +        /// reloc_pcrel_word - PC relative relocation, add the relocated
> value to
> +        /// the value already in memory, after we adjust it for where the
> PC is.
> +        reloc_pcrel_word = 0,
> +
> +        /// reloc_picrel_word - PIC base relative relocation, add the
> relocated
> +        /// value to the value already in memory, after we adjust it for
> where the
> +        /// PIC base is.
> +        reloc_picrel_word = 1,
> +
> +        /// reloc_absolute_word, reloc_absolute_dword - Absolute
> relocation, just
> +        /// add the relocated value to the value already in memory.
> +        reloc_absolute_word = 2,
> +        reloc_absolute_dword = 3
> +      };
> +    }
> +  }
> +
> +Since the body is small, indenting adds value because it makes it very
> clear
> +where the namespace starts and ends, and it is easy to take the whole
> thing in
> +in one "gulp" when reading the code.  If the blob of code in the
> namespace is
> +larger (as it typically is in a header in the ``llvm`` or ``clang``
> namespaces),
> +do not indent the code, and add a comment indicating what namespace is
> being
> +closed.  For example:
> +
> +.. code-block:: c++
> +
> +  namespace llvm {
> +  namespace knowledge {
> +
> +  /// Grokable - This class represents things that Smith can have an
> intimate
> +  /// understanding of and contains the data associated with it.
> +  class Grokable {
> +  ...
> +  public:
> +    explicit Grokable() { ... }
> +    virtual ~Grokable() = 0;
> +
> +    ...
> +
> +  };
> +
> +  } // end namespace knowledge
> +  } // end namespace llvm
> +
> +Because the class is large, we don't expect that the reader can easily
> +understand the entire concept in a glance, and the end of the file (where
> the
> +namespaces end) may be a long ways away from the place they open.  As
> such,
> +indenting the contents of the namespace doesn't add any value, and
> detracts from
> +the readability of the class.  In these cases it is best to *not* indent
> the
> +contents of the namespace.
> +
> +.. _static:
> +
> +Anonymous Namespaces
> +^^^^^^^^^^^^^^^^^^^^
> +
> +After talking about namespaces in general, you may be wondering about
> anonymous
> +namespaces in particular.  Anonymous namespaces are a great language
> feature
> +that tells the C++ compiler that the contents of the namespace are only
> visible
> +within the current translation unit, allowing more aggressive
> optimization and
> +eliminating the possibility of symbol name collisions.  Anonymous
> namespaces are
> +to C++ as "static" is to C functions and global variables.  While
> "``static``"
> +is available in C++, anonymous namespaces are more general: they can make
> entire
> +classes private to a file.
> +
> +The problem with anonymous namespaces is that they naturally want to
> encourage
> +indentation of their body, and they reduce locality of reference: if you
> see a
> +random function definition in a C++ file, it is easy to see if it is
> marked
> +static, but seeing if it is in an anonymous namespace requires scanning a
> big
> +chunk of the file.
> +
> +Because of this, we have a simple guideline: make anonymous namespaces as
> small
> +as possible, and only use them for class declarations.  For example, this
> is
> +good:
> +
> +.. code-block:: c++
> +
> +  namespace {
> +    class StringSort {
> +    ...
> +    public:
> +      StringSort(...)
> +      bool operator<(const char *RHS) const;
> +    };
> +  } // end anonymous namespace
> +
> +  static void Helper() {
> +    ...
> +  }
> +
> +  bool StringSort::operator<(const char *RHS) const {
> +    ...
> +  }
> +
> +This is bad:
> +
> +.. code-block:: c++
> +
> +  namespace {
> +  class StringSort {
> +  ...
> +  public:
> +    StringSort(...)
> +    bool operator<(const char *RHS) const;
> +  };
> +
> +  void Helper() {
> +    ...
> +  }
> +
> +  bool StringSort::operator<(const char *RHS) const {
> +    ...
> +  }
> +
> +  } // end anonymous namespace
> +
> +This is bad specifically because if you're looking at "``Helper``" in the
> middle
> +of a large C++ file, that you have no immediate way to tell if it is
> local to
> +the file.  When it is marked static explicitly, this is immediately
> obvious.
> +Also, there is no reason to enclose the definition of "``operator<``" in
> the
> +namespace just because it was declared there.
> +
> +See Also
> +========
> +
> +A lot of these comments and recommendations have been culled for other
> sources.
> +Two particularly important books for our work are:
> +
> +#. `Effective C++
> +   <
> http://www.amazon.com/Effective-Specific-Addison-Wesley-Professional-Computing/dp/0321334876
> >`_
> +   by Scott Meyers.  Also interesting and useful are "More Effective C++"
> and
> +   "Effective STL" by the same author.
> +
> +#. `Large-Scale C++ Software Design
> +   <
> http://www.amazon.com/Large-Scale-Software-Design-John-Lakos/dp/0201633620/ref=sr_1_1
> >`_
> +   by John Lakos
> +
> +If you get some free time, and you haven't read them: do so, you might
> learn
> +something.
>
> Modified: llvm/trunk/docs/development_process.rst
> URL:
> http://llvm.org/viewvc/llvm-project/llvm/trunk/docs/development_process.rst?rev=158786&r1=158785&r2=158786&view=diff
>
> ==============================================================================
> --- llvm/trunk/docs/development_process.rst (original)
> +++ llvm/trunk/docs/development_process.rst Tue Jun 19 21:57:56 2012
> @@ -7,6 +7,7 @@
>    :hidden:
>
>    Projects
> +   CodingStandards
>
>  \
>
> @@ -17,6 +18,12 @@
>    tree) allow the project code to be located outside (or inside) the
> ``llvm/``
>    tree, while using LLVM header files and libraries.
>
> + * :ref:`coding_standards`
> +
> +   Describes a few coding standards that are used in the LLVM source
> tree. All
> +   code submissions must follow the coding standards before being allowed
> into
> +   the source tree.
> +
>  * `LLVMBuild Documentation <LLVMBuild.html>`_
>
>    Describes the LLVMBuild organization and files used by LLVM to specify
>
>
> _______________________________________________
> llvm-commits mailing list
> llvm-commits at cs.uiuc.edu
> http://lists.cs.uiuc.edu/mailman/listinfo/llvm-commits
>
-------------- next part --------------
An HTML attachment was scrubbed...
URL: <http://lists.llvm.org/pipermail/llvm-commits/attachments/20120620/6a418bc1/attachment.html>


More information about the llvm-commits mailing list