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>
<!-- *********************************************************************** -->
-<h2>
- <a name="introduction">Introduction</a>
-</h2>
+<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 can be
-useful.</p>
+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
<blockquote>
-<p><b><a name="goldenrule">If you are adding a significant body of source to a
-project, feel free to use whatever style you are most comfortable with. 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>
+<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
<div>
<p>Comments are one critical part of readability and maintainability. Everyone
-knows they should comment, so should you. When writing comments, write them as
-English prose, which means they should use proper capitalization, punctuation,
-etc. Although we all should probably
-comment our code more than we do, there are a few very critical places that
-documentation is very useful:</p>
+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>
<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 Subversion. Most source trees will probably have a standard
-file header format. The standard format for the LLVM source tree looks like
-this:</p>
+checked into the tree. The standard header looks like this:</p>
<div class="doc_code">
<pre>
<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... if it's not obvious. If it's so completely obvious your grandma
-could figure it out, it's probably safe to leave it out. Naming classes
-something sane goes a long ways towards avoiding writing documentation.</p>
+used for and how it works. Every non-trivial class is expected to have a
+doxygen comment block.</p>
<h5>Method information</h5>
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... that is
-the goal metric.</p>
+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>
<p>which shuts <tt>gcc</tt> up. Any <tt>gcc</tt> warning that annoys you can
be fixed by massaging the code appropriately.</p>
-<p>These are the <tt>gcc</tt> warnings that I prefer to enable:</p>
-
-<div class="doc_code">
-<pre>
--Wall -Winline -W -Wwrite-strings -Wno-unused
-</pre>
-</div>
-
</div>
<!-- _______________________________________________________________________ -->
</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>
<div>
<p>The use of <tt>#include <iostream></tt> in library files is
-hereby <b><em>forbidden</em></b>. The primary reason for doing this is to
-support clients using LLVM libraries as part of larger systems. In particular,
-we statically link LLVM into some dynamic libraries. Even if LLVM isn't used,
-the static constructors are run whenever an application starts up that uses the
-dynamic library. There are two problems with this:</p>
-
-<ol>
- <li>The time to run the static c'tors impacts startup time of applications
- — a critical time for GUI apps.</li>
-
- <li>The static c'tors cause the app to pull many extra pages of memory off the
- disk: both the code for the static c'tors 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>
-
+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
projects / oota-llvm.git / blobdiff