2003-10-24 17:57:33 +00:00
|
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
|
|
|
|
"http://www.w3.org/TR/html4/strict.dtd">
|
|
|
|
|
<html>
|
|
|
|
|
<head>
|
|
|
|
|
<link rel="stylesheet" href="llvm.css" type="text/css">
|
2008-12-10 23:07:02 +00:00
|
|
|
<title>LLVM Coding Standards</title>
|
2003-10-24 17:57:33 +00:00
|
|
|
</head>
|
|
|
|
|
<body>
|
|
|
|
|
|
|
|
|
|
<div class="doc_title">
|
2008-12-10 23:07:02 +00:00
|
|
|
LLVM Coding Standards
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
<ol>
|
2003-10-24 17:57:33 +00:00
|
|
|
<li><a href="#introduction">Introduction</a></li>
|
2001-07-23 20:40:41 +00:00
|
|
|
<li><a href="#mechanicalissues">Mechanical Source Issues</a>
|
2001-07-09 03:27:08 +00:00
|
|
|
<ol>
|
|
|
|
|
<li><a href="#sourceformating">Source Code Formatting</a>
|
2003-10-24 17:57:33 +00:00
|
|
|
<ol>
|
|
|
|
|
<li><a href="#scf_commenting">Commenting</a></li>
|
|
|
|
|
<li><a href="#scf_commentformat">Comment Formatting</a></li>
|
2004-10-26 16:18:43 +00:00
|
|
|
<li><a href="#scf_includes"><tt>#include</tt> Style</a></li>
|
2003-10-24 17:57:33 +00:00
|
|
|
<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>
|
2001-07-09 03:27:08 +00:00
|
|
|
<li><a href="#compilerissues">Compiler Issues</a>
|
|
|
|
|
<ol>
|
2003-10-24 17:57:33 +00:00
|
|
|
<li><a href="#ci_warningerrors">Treat Compiler Warnings Like
|
|
|
|
|
Errors</a></li>
|
|
|
|
|
<li><a href="#ci_portable_code">Write Portable Code</a></li>
|
2010-11-30 19:20:40 +00:00
|
|
|
<li><a href="#ci_rtti_exceptions">Do not use RTTI or Exceptions</a></li>
|
2010-11-23 05:03:07 +00:00
|
|
|
<li><a href="#ci_class_struct">Use of <tt>class</tt>/<tt>struct</tt> Keywords</a></li>
|
2003-10-24 17:57:33 +00:00
|
|
|
</ol></li>
|
|
|
|
|
</ol></li>
|
2001-07-09 03:27:08 +00:00
|
|
|
<li><a href="#styleissues">Style Issues</a>
|
|
|
|
|
<ol>
|
2010-11-17 17:14:55 +00:00
|
|
|
<li><a href="#macro">The High-Level Issues</a>
|
2001-07-09 03:27:08 +00:00
|
|
|
<ol>
|
2003-10-24 17:57:33 +00:00
|
|
|
<li><a href="#hl_module">A Public Header File <b>is</b> a
|
|
|
|
|
Module</a></li>
|
2010-11-23 05:03:07 +00:00
|
|
|
<li><a href="#hl_dontinclude"><tt>#include</tt> as Little as Possible</a></li>
|
2003-10-24 17:57:33 +00:00
|
|
|
<li><a href="#hl_privateheaders">Keep "internal" Headers
|
|
|
|
|
Private</a></li>
|
2010-11-23 05:03:07 +00:00
|
|
|
<li><a href="#hl_earlyexit">Use Early Exits and <tt>continue</tt> to Simplify
|
2009-07-22 05:40:54 +00:00
|
|
|
Code</a></li>
|
2010-11-23 05:03:07 +00:00
|
|
|
<li><a href="#hl_else_after_return">Don't use <tt>else</tt> after a
|
|
|
|
|
<tt>return</tt></a></li>
|
2009-07-22 05:40:54 +00:00
|
|
|
<li><a href="#hl_predicateloops">Turn Predicate Loops into Predicate
|
|
|
|
|
Functions</a></li>
|
2003-10-24 17:57:33 +00:00
|
|
|
</ol></li>
|
2010-11-17 17:14:55 +00:00
|
|
|
<li><a href="#micro">The Low-Level Issues</a>
|
2001-07-09 03:27:08 +00:00
|
|
|
<ol>
|
2010-12-02 05:10:07 +00:00
|
|
|
<li><a href="#ll_naming">Name Types, Functions, Variables, and Enumerators Properly</a></li>
|
2006-07-27 04:24:14 +00:00
|
|
|
<li><a href="#ll_assert">Assert Liberally</a></li>
|
2010-11-23 05:03:07 +00:00
|
|
|
<li><a href="#ll_ns_std">Do not use '<tt>using namespace std</tt>'</a></li>
|
2006-12-09 01:20:34 +00:00
|
|
|
<li><a href="#ll_virtual_anch">Provide a virtual method anchor for
|
2006-12-09 01:35:43 +00:00
|
|
|
classes in headers</a></li>
|
2010-11-23 05:03:07 +00:00
|
|
|
<li><a href="#ll_end">Don't evaluate <tt>end()</tt> every time through a
|
2009-06-30 06:13:23 +00:00
|
|
|
loop</a></li>
|
2009-07-22 05:40:54 +00:00
|
|
|
<li><a href="#ll_iostream"><tt>#include <iostream></tt> is
|
|
|
|
|
<em>forbidden</em></a></li>
|
2010-12-10 00:54:03 +00:00
|
|
|
<li><a href="#ll_raw_ostream">Use <tt>raw_ostream</tt></a></li>
|
2010-11-17 17:14:55 +00:00
|
|
|
<li><a href="#ll_avoidendl">Avoid <tt>std::endl</tt></a></li>
|
2003-10-24 17:57:33 +00:00
|
|
|
</ol></li>
|
2009-07-22 05:40:54 +00:00
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
</ol></li>
|
|
|
|
|
<li><a href="#seealso">See Also</a></li>
|
|
|
|
|
</ol>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2004-05-23 21:05:07 +00:00
|
|
|
<div class="doc_author">
|
2009-07-22 05:43:01 +00:00
|
|
|
<p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></p>
|
2004-05-23 21:05:07 +00:00
|
|
|
</div>
|
|
|
|
|
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_section">
|
|
|
|
|
<a name="introduction">Introduction</a>
|
|
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_text">
|
|
|
|
|
|
|
|
|
|
<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
|
2003-10-06 19:26:00 +00:00
|
|
|
absolute requirements to be followed in all instances, coding standards can be
|
2003-10-24 17:57:33 +00:00
|
|
|
useful.</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<p>This document intentionally does not prescribe fixed standards for religious
|
2003-10-06 19:26:00 +00:00
|
|
|
issues such as brace placement and space usage. For issues like this, follow
|
2003-10-24 17:57:33 +00:00
|
|
|
the golden rule:</p>
|
|
|
|
|
|
|
|
|
|
<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>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
</blockquote>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<p>The ultimate goal of these guidelines is the increase readability and
|
2003-10-06 19:26:00 +00:00
|
|
|
maintainability of our common source base. If you have suggestions for topics to
|
2003-10-24 17:57:33 +00:00
|
|
|
be included, please mail them to <a
|
|
|
|
|
href="mailto:sabre@nondot.org">Chris</a>.</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_section">
|
|
|
|
|
<a name="mechanicalissues">Mechanical Source Issues</a>
|
|
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<!-- ======================================================================= -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="sourceformating">Source Code Formatting</a>
|
|
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="scf_commenting">Commenting</a>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<p>Comments are one critical part of readability and maintainability. Everyone
|
2009-07-12 00:10:24 +00:00
|
|
|
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
|
2003-10-06 19:26:00 +00:00
|
|
|
comment our code more than we do, there are a few very critical places that
|
2003-10-24 17:57:33 +00:00
|
|
|
documentation is very useful:</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2004-05-23 21:05:07 +00:00
|
|
|
<b>File Headers</b>
|
2003-10-24 17:57:33 +00:00
|
|
|
|
2007-07-09 08:04:31 +00:00
|
|
|
<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
|
2003-10-24 17:57:33 +00:00
|
|
|
file header format. The standard format for the LLVM source tree looks like
|
|
|
|
|
this:</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2004-07-28 22:31:54 +00:00
|
|
|
<div class="doc_code">
|
2001-07-09 03:27:08 +00:00
|
|
|
<pre>
|
2003-10-13 14:58:11 +00:00
|
|
|
//===-- llvm/Instruction.h - Instruction class definition -------*- C++ -*-===//
|
2009-01-02 16:58:42 +00:00
|
|
|
//
|
2004-05-23 21:05:07 +00:00
|
|
|
// The LLVM Compiler Infrastructure
|
|
|
|
|
//
|
2007-12-29 19:56:08 +00:00
|
|
|
// This file is distributed under the University of Illinois Open Source
|
|
|
|
|
// License. See LICENSE.TXT for details.
|
2009-01-02 16:58:42 +00:00
|
|
|
//
|
2004-05-23 21:05:07 +00:00
|
|
|
//===----------------------------------------------------------------------===//
|
2001-07-09 03:27:08 +00:00
|
|
|
//
|
|
|
|
|
// This file contains the declaration of the Instruction class, which is the
|
|
|
|
|
// base class for all of the VM instructions.
|
|
|
|
|
//
|
|
|
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
|
</pre>
|
2004-07-28 22:31:54 +00:00
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2007-12-29 19:56:08 +00:00
|
|
|
<p>A few things to note about this particular format: The "<tt>-*- C++
|
2003-10-24 17:57:33 +00:00
|
|
|
-*-</tt>" string on the first line is there to tell Emacs that the source file
|
2010-11-17 17:14:55 +00:00
|
|
|
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
|
2004-07-28 22:37:57 +00:00
|
|
|
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>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2007-12-29 19:56:08 +00:00
|
|
|
<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>
|
2004-05-23 21:05:07 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<p>The main body of the description does not have to be very long in most cases.
|
2003-10-06 19:26:00 +00:00
|
|
|
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
|
2003-10-24 17:57:33 +00:00
|
|
|
included, as well as any notes or "gotchas" in the code to watch out for.</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2004-05-23 21:05:07 +00:00
|
|
|
<b>Class overviews</b>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2006-07-31 20:18:49 +00:00
|
|
|
<p>Classes are one fundamental part of a good object oriented design. As such,
|
2003-10-24 17:57:33 +00:00
|
|
|
a class definition should have a comment block that explains what the class is
|
2003-10-06 19:26:00 +00:00
|
|
|
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
|
2004-12-04 00:32:12 +00:00
|
|
|
something sane goes a long ways towards avoiding writing documentation.</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
|
2004-05-23 21:05:07 +00:00
|
|
|
<b>Method information</b>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<p>Methods defined in a class (as well as any global functions) should also be
|
2010-02-26 20:18:32 +00:00
|
|
|
documented properly. A quick note about what it does and a description of the
|
2003-10-06 19:26:00 +00:00
|
|
|
borderline behaviour is all that is necessary here (unless something
|
2010-02-26 20:18:32 +00:00
|
|
|
particularly tricky or insidious is going on). The hope is that people can
|
2003-10-06 19:26:00 +00:00
|
|
|
figure out how to use your interfaces without reading the code itself... that is
|
2003-10-24 17:57:33 +00:00
|
|
|
the goal metric.</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<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>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="scf_commentformat">Comment Formatting</a>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<p>In general, prefer C++ style (<tt>//</tt>) comments. They take less space,
|
2003-10-06 19:26:00 +00:00
|
|
|
require less typing, don't have nesting problems, etc. There are a few cases
|
2003-10-24 17:57:33 +00:00
|
|
|
when it is useful to use C style (<tt>/* */</tt>) comments however:</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
<ol>
|
2010-12-21 03:31:05 +00:00
|
|
|
<li>When writing C code: Obviously if you are writing C code, use C style
|
2004-12-04 00:32:12 +00:00
|
|
|
comments.</li>
|
2004-10-26 16:18:43 +00:00
|
|
|
<li>When writing a header file that may be <tt>#include</tt>d by a C source
|
|
|
|
|
file.</li>
|
2003-10-24 17:57:33 +00:00
|
|
|
<li>When writing a source file that is used by a tool that only accepts C
|
|
|
|
|
style comments.</li>
|
|
|
|
|
</ol>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<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>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-08-07 21:45:47 +00:00
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_subsubsection">
|
2004-10-26 16:18:43 +00:00
|
|
|
<a name="scf_includes"><tt>#include</tt> Style</a>
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2003-08-07 21:45:47 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<p>Immediately after the <a href="#scf_commenting">header file comment</a> (and
|
2003-08-07 21:45:47 +00:00
|
|
|
include guards if working on a header file), the <a
|
2004-07-28 22:31:54 +00:00
|
|
|
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>
|
2003-08-07 21:45:47 +00:00
|
|
|
|
|
|
|
|
<ol>
|
2010-11-17 17:14:55 +00:00
|
|
|
<li><a href="#mmheader">Main Module Header</a></li>
|
2003-10-24 17:57:33 +00:00
|
|
|
<li><a href="#hl_privateheaders">Local/Private Headers</a></li>
|
2004-07-28 22:31:54 +00:00
|
|
|
<li><tt>llvm/*</tt></li>
|
|
|
|
|
<li><tt>llvm/Analysis/*</tt></li>
|
|
|
|
|
<li><tt>llvm/Assembly/*</tt></li>
|
2010-09-29 20:09:55 +00:00
|
|
|
<li><tt>llvm/Bitcode/*</tt></li>
|
2004-07-28 22:31:54 +00:00
|
|
|
<li><tt>llvm/CodeGen/*</tt></li>
|
2003-10-24 17:57:33 +00:00
|
|
|
<li>...</li>
|
2004-07-28 22:31:54 +00:00
|
|
|
<li><tt>Support/*</tt></li>
|
|
|
|
|
<li><tt>Config/*</tt></li>
|
|
|
|
|
<li>System <tt>#includes</tt></li>
|
2003-08-07 21:45:47 +00:00
|
|
|
</ol>
|
|
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<p>and each category should be sorted by name.</p>
|
2003-08-07 21:45:47 +00:00
|
|
|
|
2010-11-17 17:14:55 +00:00
|
|
|
<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>
|
2004-10-26 16:18:43 +00:00
|
|
|
should always be included <b>first</b> regardless of where it lives on the file
|
2010-11-17 17:14:55 +00:00
|
|
|
system. By including a header file first in the <tt>.cpp</tt> files that implement the
|
2004-10-26 16:18:43 +00:00
|
|
|
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
|
2010-11-17 17:14:55 +00:00
|
|
|
form of documentation in the <tt>.cpp</tt> file to indicate where the interfaces it
|
2004-10-26 16:18:43 +00:00
|
|
|
implements are defined.</p>
|
2003-08-07 21:45:47 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="scf_codewidth">Source Code Width</a>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<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>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2008-07-08 05:12:37 +00:00
|
|
|
<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>
|
|
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<p>This is one of many contentious issues in coding standards, but it is not up
|
2008-07-08 05:12:37 +00:00
|
|
|
for debate.</p>
|
|
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="scf_spacestabs">Use Spaces Instead of Tabs</a>
|
|
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_text">
|
|
|
|
|
|
|
|
|
|
<p>In all cases, prefer spaces to tabs in source files. People have different
|
2009-10-12 14:46:08 +00:00
|
|
|
preferred indentation levels, and different styles of indentation that they
|
2010-12-21 03:31:05 +00:00
|
|
|
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
|
2003-10-24 17:57:33 +00:00
|
|
|
unreadable, and it is not worth dealing with.</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<p>As always, follow the <a href="#goldenrule">Golden Rule</a> above: follow the
|
2010-12-21 03:31:05 +00:00
|
|
|
style of existing code if you are modifying and extending it. If you like four
|
2003-10-06 19:26:00 +00:00
|
|
|
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
|
2003-10-24 17:57:33 +00:00
|
|
|
makes for incredible diffs that are absolutely worthless.</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="scf_indentation">Indent Code Consistently</a>
|
|
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_text">
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2010-11-17 17:14:55 +00:00
|
|
|
<p>Okay, in your first year of programming you were told that indentation is
|
2003-10-24 17:57:33 +00:00
|
|
|
important. If you didn't believe and internalize this then, now is the time.
|
|
|
|
|
Just do it.</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ======================================================================= -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="compilerissues">Compiler Issues</a>
|
|
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="ci_warningerrors">Treat Compiler Warnings Like Errors</a>
|
|
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_text">
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<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
|
2003-10-24 17:57:33 +00:00
|
|
|
difficult.</p>
|
|
|
|
|
|
|
|
|
|
<p>It is not possible to prevent all warnings from all compilers, nor is it
|
2003-10-06 19:26:00 +00:00
|
|
|
desirable. Instead, pick a standard compiler (like <tt>gcc</tt>) that provides
|
2010-12-21 03:31:05 +00:00
|
|
|
a good thorough set of warnings, and stick to it. At least in the case of
|
2003-10-06 19:26:00 +00:00
|
|
|
<tt>gcc</tt>, it is possible to work around any spurious errors by changing the
|
2010-12-21 03:31:05 +00:00
|
|
|
syntax of the code slightly. For example, a warning that annoys me occurs when
|
2003-10-24 17:57:33 +00:00
|
|
|
I write code like this:</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2004-07-28 22:31:54 +00:00
|
|
|
<div class="doc_code">
|
2001-07-09 03:27:08 +00:00
|
|
|
<pre>
|
2004-07-28 22:31:54 +00:00
|
|
|
if (V = getValue()) {
|
|
|
|
|
...
|
|
|
|
|
}
|
2003-10-24 17:57:33 +00:00
|
|
|
</pre>
|
2004-07-28 22:31:54 +00:00
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<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>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2004-07-28 22:31:54 +00:00
|
|
|
<div class="doc_code">
|
2001-07-09 03:27:08 +00:00
|
|
|
<pre>
|
2004-07-28 22:31:54 +00:00
|
|
|
if ((V = getValue())) {
|
|
|
|
|
...
|
|
|
|
|
}
|
2003-10-24 17:57:33 +00:00
|
|
|
</pre>
|
2004-07-28 22:31:54 +00:00
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<p>which shuts <tt>gcc</tt> up. Any <tt>gcc</tt> warning that annoys you can
|
2003-10-24 17:57:33 +00:00
|
|
|
be fixed by massaging the code appropriately.</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<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>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="ci_portable_code">Write Portable Code</a>
|
|
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_text">
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<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>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<p>In practice, this means that you shouldn't assume much about the host
|
2010-11-16 22:19:06 +00:00
|
|
|
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>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2004-09-23 16:03:48 +00:00
|
|
|
<!-- _______________________________________________________________________ -->
|
2010-11-30 19:20:40 +00:00
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="ci_rtti_exceptions">Do not use RTTI or Exceptions</a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<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>
|
2010-11-30 19:20:40 +00:00
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<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>
|
2010-11-30 19:20:40 +00:00
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2004-09-23 16:03:48 +00:00
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="ci_class_struct">Use of <tt>class</tt> and <tt>struct</tt> Keywords</a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
2004-10-26 15:45:13 +00:00
|
|
|
|
|
|
|
|
<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
|
2010-12-21 03:31:05 +00:00
|
|
|
<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>
|
2004-10-26 15:45:13 +00:00
|
|
|
|
2004-09-23 16:03:48 +00:00
|
|
|
</div>
|
|
|
|
|
|
2001-07-09 03:27:08 +00:00
|
|
|
<!-- *********************************************************************** -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_section">
|
|
|
|
|
<a name="styleissues">Style Issues</a>
|
|
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ======================================================================= -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_subsection">
|
2010-11-17 17:14:55 +00:00
|
|
|
<a name="macro">The High-Level Issues</a>
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
2009-07-22 05:40:54 +00:00
|
|
|
<!-- ======================================================================= -->
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="hl_module">A Public Header File <b>is</b> a Module</a>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<p>C++ doesn't do too well in the modularity department. There is no real
|
2003-07-28 21:57:18 +00:00
|
|
|
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
|
2010-12-21 03:31:05 +00:00
|
|
|
source tree, they live in the top level "<tt>include</tt>" directory), you are
|
|
|
|
|
defining a module of functionality.</p>
|
2003-07-28 21:57:18 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<p>Ideally, modules should be completely independent of each other, and their
|
2010-12-21 03:31:05 +00:00
|
|
|
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>
|
2003-10-24 17:57:33 +00:00
|
|
|
files. Each of these <tt>.cpp</tt> files should include the header that defines
|
2010-11-17 17:14:55 +00:00
|
|
|
their interface first. This ensures that all of the dependences of the module
|
2003-10-24 17:57:33 +00:00
|
|
|
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>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_subsubsection">
|
2004-10-26 16:18:43 +00:00
|
|
|
<a name="hl_dontinclude"><tt>#include</tt> as Little as Possible</a>
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_text">
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<p><tt>#include</tt> hurts compile time performance. Don't do it unless you
|
|
|
|
|
have to, especially in header files.</p>
|
|
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<p>But wait! Sometimes you need to have the definition of a class to use it, or
|
2004-10-26 16:18:43 +00:00
|
|
|
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
|
2010-12-21 03:31:05 +00:00
|
|
|
most cases, you simply don't need the definition of a class. And not
|
2004-10-26 16:18:43 +00:00
|
|
|
<tt>#include</tt>'ing speeds up compilation.</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<p>It is easy to try to go too overboard on this recommendation, however. You
|
2010-12-21 03:31:05 +00:00
|
|
|
<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>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_subsubsection">
|
2010-12-21 03:31:05 +00:00
|
|
|
<a name="hl_privateheaders">Keep "Internal" Headers Private</a>
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<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
|
2010-12-21 03:31:05 +00:00
|
|
|
public module header file. Don't do this!</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<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>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<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>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2006-12-09 01:20:34 +00:00
|
|
|
<!-- _______________________________________________________________________ -->
|
|
|
|
|
<div class="doc_subsubsection">
|
2010-11-23 05:03:07 +00:00
|
|
|
<a name="hl_earlyexit">Use Early Exits and <tt>continue</tt> to Simplify Code</a>
|
2006-12-09 01:20:34 +00:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
|
2009-07-22 05:40:54 +00:00
|
|
|
<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
|
2010-12-21 03:31:05 +00:00
|
|
|
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>
|
2006-12-09 01:20:34 +00:00
|
|
|
|
2009-07-22 05:40:54 +00:00
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
|
|
|
|
Value *DoSomething(Instruction *I) {
|
|
|
|
|
if (!isa<TerminatorInst>(I) &&
|
|
|
|
|
I->hasOneUse() && SomeOtherThing(I)) {
|
|
|
|
|
... some long code ....
|
|
|
|
|
}
|
|
|
|
|
|
|
|
|
|
return 0;
|
|
|
|
|
}
|
|
|
|
|
</pre>
|
|
|
|
|
</div>
|
2006-12-09 01:20:34 +00:00
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<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>
|
2008-07-30 12:14:10 +00:00
|
|
|
|
2009-07-22 05:40:54 +00:00
|
|
|
<p>It is much preferred to format the code like this:</p>
|
|
|
|
|
|
|
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
|
|
|
|
Value *DoSomething(Instruction *I) {
|
2010-12-21 03:31:05 +00:00
|
|
|
// Terminators never need 'something' done to them because ...
|
2009-07-22 05:40:54 +00:00
|
|
|
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>
|
|
|
|
|
|
2010-11-17 17:14:55 +00:00
|
|
|
<p>This fixes these problems. A similar problem frequently happens in <tt>for</tt>
|
2009-07-22 05:40:54 +00:00
|
|
|
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>
|
|
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<p>When you have very, very small loops, this sort of structure is fine. But if
|
2009-07-22 05:40:54 +00:00
|
|
|
it exceeds more than 10-15 lines, it becomes difficult for people to read and
|
2010-12-21 03:31:05 +00:00
|
|
|
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>
|
2009-07-22 05:40:54 +00:00
|
|
|
|
|
|
|
|
<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;
|
2010-12-21 03:31:05 +00:00
|
|
|
|
2010-11-17 17:14:55 +00:00
|
|
|
...
|
2009-07-22 05:40:54 +00:00
|
|
|
}
|
|
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<p>This has all the benefits of using early exits for functions: it reduces
|
2009-07-22 05:40:54 +00:00
|
|
|
nesting of the loop, it makes it easier to describe why the conditions are true,
|
2010-12-21 03:31:05 +00:00
|
|
|
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>
|
2009-07-22 05:40:54 +00:00
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
2009-07-28 22:54:04 +00:00
|
|
|
<!-- _______________________________________________________________________ -->
|
|
|
|
|
<div class="doc_subsubsection">
|
2010-11-23 05:03:07 +00:00
|
|
|
<a name="hl_else_after_return">Don't use <tt>else</tt> after a <tt>return</tt></a>
|
2009-07-28 22:54:04 +00:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
|
|
|
|
|
<p>For similar reasons above (reduction of indentation and easier reading),
|
2010-12-21 03:31:05 +00:00
|
|
|
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>
|
|
|
|
|
|
2009-07-28 22:54:04 +00:00
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
|
|
|
|
case 'J': {
|
|
|
|
|
if (Signed) {
|
|
|
|
|
Type = Context.getsigjmp_bufType();
|
|
|
|
|
if (Type.isNull()) {
|
|
|
|
|
Error = ASTContext::GE_Missing_sigjmp_buf;
|
|
|
|
|
return QualType();
|
2010-12-21 03:31:05 +00:00
|
|
|
<b>} else {
|
2009-07-28 22:54:04 +00:00
|
|
|
break;
|
2010-12-21 03:31:05 +00:00
|
|
|
}</b>
|
2009-07-28 22:54:04 +00:00
|
|
|
} else {
|
|
|
|
|
Type = Context.getjmp_bufType();
|
|
|
|
|
if (Type.isNull()) {
|
|
|
|
|
Error = ASTContext::GE_Missing_jmp_buf;
|
|
|
|
|
return QualType();
|
2010-12-21 03:31:05 +00:00
|
|
|
<b>} else {
|
2009-07-28 22:54:04 +00:00
|
|
|
break;
|
2010-12-21 03:31:05 +00:00
|
|
|
}</b>
|
2009-07-28 22:54:04 +00:00
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
}
|
|
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<p>It is better to write it like this:</p>
|
2009-07-28 22:54:04 +00:00
|
|
|
|
|
|
|
|
<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();
|
|
|
|
|
}
|
|
|
|
|
}
|
2010-12-21 03:31:05 +00:00
|
|
|
<b>break;</b>
|
2009-07-28 22:54:04 +00:00
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<p>Or better yet (in this case) as:</p>
|
2009-07-28 22:54:04 +00:00
|
|
|
|
|
|
|
|
<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();
|
|
|
|
|
}
|
2010-12-21 03:31:05 +00:00
|
|
|
<b>break;</b>
|
2009-07-28 22:54:04 +00:00
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<p>The idea is to reduce indentation and the amount of code you have to keep
|
2010-12-21 03:31:05 +00:00
|
|
|
track of when reading the code.</p>
|
2009-07-28 22:54:04 +00:00
|
|
|
|
|
|
|
|
</div>
|
2009-07-22 05:40:54 +00:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
|
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="hl_predicateloops">Turn Predicate Loops into Predicate Functions</a>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<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>
|
2009-07-22 05:40:54 +00:00
|
|
|
|
|
|
|
|
<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
|
2009-07-22 16:54:14 +00:00
|
|
|
<a href="#hl_earlyexit">early exits</a> to compute the predicate. We prefer
|
2010-12-21 03:31:05 +00:00
|
|
|
the code to be structured like this:</p>
|
2009-07-22 05:40:54 +00:00
|
|
|
|
|
|
|
|
<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
|
2009-07-22 16:30:39 +00:00
|
|
|
of being faced with the in-line details of how we check to see if the BarList
|
2009-07-22 05:40:54 +00:00
|
|
|
contains a foo, we can trust the function name and continue reading with better
|
|
|
|
|
locality.</p>
|
2006-12-09 01:20:34 +00:00
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
2001-07-09 03:27:08 +00:00
|
|
|
<!-- ======================================================================= -->
|
2004-05-23 21:05:07 +00:00
|
|
|
<div class="doc_subsection">
|
2010-11-17 17:14:55 +00:00
|
|
|
<a name="micro">The Low-Level Issues</a>
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
2009-07-22 05:40:54 +00:00
|
|
|
<!-- ======================================================================= -->
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
|
2010-12-02 05:10:07 +00:00
|
|
|
<!-- _______________________________________________________________________ -->
|
|
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="ll_naming">Name Types, Functions, Variables, and Enumerators Properly</a>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2010-12-21 03:31:05 +00:00
|
|
|
|
|
|
|
|
<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>
|
2010-12-10 00:52:35 +00:00
|
|
|
|
|
|
|
|
<p>In general, names should be in camel case (e.g. <tt>TextFileReader</tt>
|
2010-12-21 03:31:05 +00:00
|
|
|
and <tt>isLValue()</tt>). Different kinds of declarations have different
|
|
|
|
|
rules:</p>
|
2010-12-10 00:52:35 +00:00
|
|
|
|
|
|
|
|
<ul>
|
2010-12-10 00:54:03 +00:00
|
|
|
<li><p><b>Type names</b> (including classes, structs, enums, typedefs, etc)
|
|
|
|
|
should be nouns and start with an upper-case letter (e.g.
|
2010-12-21 03:31:05 +00:00
|
|
|
<tt>TextFileReader</tt>).</p></li>
|
2010-12-10 00:52:35 +00:00
|
|
|
|
2010-12-10 00:54:03 +00:00
|
|
|
<li><p><b>Function names</b> should be verb phrases (as they represent
|
2010-12-10 00:52:35 +00:00
|
|
|
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>
|
2010-12-21 03:31:05 +00:00
|
|
|
or <tt>isFoo()</tt>).</p></li>
|
2010-12-10 00:52:35 +00:00
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<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>
|
2010-12-10 00:52:35 +00:00
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<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>
|
|
|
|
|
|
2010-12-02 05:10:07 +00:00
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
|
|
|
|
enum {
|
|
|
|
|
MaxSize = 42,
|
|
|
|
|
Density = 12
|
|
|
|
|
};
|
|
|
|
|
</pre>
|
|
|
|
|
</div>
|
2010-12-10 00:52:35 +00:00
|
|
|
</li>
|
2010-12-21 03:31:05 +00:00
|
|
|
|
2010-12-10 00:52:35 +00:00
|
|
|
</ul>
|
|
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<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>
|
2010-12-10 00:52:35 +00:00
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<p>Here are some examples of good and bad names:</p>
|
2010-12-02 05:10:07 +00:00
|
|
|
|
|
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
|
|
|
|
class VehicleMaker {
|
|
|
|
|
...
|
2010-12-10 00:52:35 +00:00
|
|
|
Factory<Tire> F; // Bad -- abbreviation and non-descriptive.
|
|
|
|
|
Factory<Tire> Factory; // Better.
|
|
|
|
|
Factory<Tire> TireFactory; // Even better -- if VehicleMaker has more than one
|
2010-12-02 05:10:07 +00:00
|
|
|
// kind of factories.
|
|
|
|
|
};
|
|
|
|
|
|
|
|
|
|
Vehicle MakeVehicle(VehicleType Type) {
|
2010-12-21 03:31:05 +00:00
|
|
|
VehicleMaker M; // Might be OK if having a short life-span.
|
|
|
|
|
Tire tmp1 = M.makeTire(); // Bad -- 'tmp1' provides no information.
|
2010-12-10 00:52:35 +00:00
|
|
|
Light headlight = M.makeLight("head"); // Good -- descriptive.
|
2010-12-02 05:10:07 +00:00
|
|
|
...
|
|
|
|
|
}
|
|
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
2001-07-09 03:27:08 +00:00
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_subsubsection">
|
2006-07-27 04:24:14 +00:00
|
|
|
<a name="ll_assert">Assert Liberally</a>
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2010-11-17 17:14:55 +00:00
|
|
|
<p>Use the "<tt>assert</tt>" macro to its fullest. Check all of your
|
2009-10-12 14:46:08 +00:00
|
|
|
preconditions and assumptions, you never know when a bug (not necessarily even
|
2003-07-28 21:57:18 +00:00
|
|
|
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
|
2003-10-24 17:57:33 +00:00
|
|
|
it.</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<p>To further assist with debugging, make sure to put some kind of error message
|
2010-12-21 03:31:05 +00:00
|
|
|
in the assertion statement, which is printed if the assertion is tripped. This
|
2010-11-17 17:14:55 +00:00
|
|
|
helps the poor debugger make sense of why an assertion is being made and
|
2003-10-24 17:57:33 +00:00
|
|
|
enforced, and hopefully what to do about it. Here is one complete example:</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2004-07-28 22:31:54 +00:00
|
|
|
<div class="doc_code">
|
2001-07-09 03:27:08 +00:00
|
|
|
<pre>
|
2004-07-28 22:31:54 +00:00
|
|
|
inline Value *getOperand(unsigned i) {
|
|
|
|
|
assert(i < Operands.size() && "getOperand() out of range!");
|
|
|
|
|
return Operands[i];
|
|
|
|
|
}
|
2001-07-09 03:27:08 +00:00
|
|
|
</pre>
|
2004-07-28 22:31:54 +00:00
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<p>Here are more examples:</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2004-07-28 22:31:54 +00:00
|
|
|
<div class="doc_code">
|
2001-07-09 03:27:08 +00:00
|
|
|
<pre>
|
2004-07-28 22:31:54 +00:00
|
|
|
assert(Ty->isPointerType() && "Can't allocate a non pointer type!");
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2004-07-28 22:31:54 +00:00
|
|
|
assert((Opcode == Shl || Opcode == Shr) && "ShiftInst Opcode invalid!");
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2004-07-28 22:31:54 +00:00
|
|
|
assert(idx < getNumSuccessors() && "Successor # out of range!");
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2004-07-28 22:31:54 +00:00
|
|
|
assert(V1.getType() == V2.getType() && "Constant types must be identical!");
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2004-07-28 22:31:54 +00:00
|
|
|
assert(isa<PHINode>(Succ->front()) && "Only works on PHId BBs!");
|
2003-10-24 17:57:33 +00:00
|
|
|
</pre>
|
2004-07-28 22:31:54 +00:00
|
|
|
</div>
|
2003-10-24 17:57:33 +00:00
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<p>You get the idea.</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<p>Please be aware that, when adding assert statements, not all compilers are aware of
|
2008-05-31 23:54:55 +00:00
|
|
|
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>
|
2008-11-24 17:18:39 +00:00
|
|
|
assert(0 && "Some helpful error message");
|
2008-05-31 23:54:55 +00:00
|
|
|
</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>
|
2008-11-24 17:18:39 +00:00
|
|
|
assert(0 && "Some helpful error message");
|
2008-05-31 23:54:55 +00:00
|
|
|
// Not reached
|
|
|
|
|
return 0;
|
|
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
2010-11-12 00:19:41 +00:00
|
|
|
<p>Another issue is that values used only by assertions will produce an "unused
|
2010-12-21 03:31:05 +00:00
|
|
|
value" warning when assertions are disabled. For example, this code will
|
|
|
|
|
warn:</p>
|
2010-11-12 00:19:41 +00:00
|
|
|
|
|
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
2010-12-21 03:31:05 +00:00
|
|
|
unsigned Size = V.size();
|
|
|
|
|
assert(Size > 42 && "Vector smaller than it should be");
|
2010-11-12 00:19:41 +00:00
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
bool NewToSet = Myset.insert(Value);
|
|
|
|
|
assert(NewToSet && "The value shouldn't be in the set yet");
|
2010-11-12 00:19:41 +00:00
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<p>These are two interesting different cases. In the first case, the call to
|
2010-11-12 00:19:41 +00:00
|
|
|
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
|
2010-12-21 03:31:05 +00:00
|
|
|
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>
|
2010-11-12 00:19:41 +00:00
|
|
|
|
|
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
2010-12-21 03:31:05 +00:00
|
|
|
assert(V.size() > 42 && "Vector smaller than it should be");
|
2010-11-12 00:19:41 +00:00
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
bool NewToSet = Myset.insert(Value); (void)NewToSet;
|
|
|
|
|
assert(NewToSet && "The value shouldn't be in the set yet");
|
2010-11-12 00:19:41 +00:00
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2006-01-01 21:59:22 +00:00
|
|
|
<!-- _______________________________________________________________________ -->
|
|
|
|
|
<div class="doc_subsubsection">
|
2010-12-21 03:31:05 +00:00
|
|
|
<a name="ll_ns_std">Do Not Use '<tt>using namespace std</tt>'</a>
|
2006-01-01 21:59:22 +00:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2010-12-21 03:31:05 +00:00
|
|
|
|
2006-01-01 21:59:22 +00:00
|
|
|
<p>In LLVM, we prefer to explicitly prefix all identifiers from the standard
|
2006-12-09 01:35:43 +00:00
|
|
|
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
|
2008-12-11 19:37:04 +00:00
|
|
|
the namespace of any source file that <tt>#include</tt>s the header. This is
|
|
|
|
|
clearly a bad thing.</p>
|
2006-12-09 01:35:43 +00:00
|
|
|
|
2010-11-17 17:14:55 +00:00
|
|
|
<p>In implementation files (e.g. <tt>.cpp</tt> files), the rule is more of a stylistic
|
2006-12-09 01:35:43 +00:00
|
|
|
rule, but is still important. Basically, using explicit namespace prefixes
|
|
|
|
|
makes the code <b>clearer</b>, because it is immediately obvious what facilities
|
2010-12-21 03:31:05 +00:00
|
|
|
are being used and where they are coming from. And <b>more portable</b>, because
|
2006-12-09 01:35:43 +00:00
|
|
|
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.
|
2010-11-17 19:47:20 +00:00
|
|
|
As such, it is ok, and actually clearer, for the <tt>.cpp</tt> files to have a
|
2010-12-21 03:31:05 +00:00
|
|
|
'<tt>using namespace llvm;</tt>' directive at the top, after the
|
2010-11-17 19:47:20 +00:00
|
|
|
<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>
|
2006-01-01 21:59:22 +00:00
|
|
|
|
|
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_subsubsection">
|
2010-12-21 03:31:05 +00:00
|
|
|
<a name="ll_virtual_anch">Provide a Virtual Method Anchor for Classes
|
|
|
|
|
in Headers</a>
|
2006-07-27 04:24:14 +00:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
|
|
|
|
|
<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
|
2008-12-11 19:37:04 +00:00
|
|
|
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>
|
2006-07-27 04:24:14 +00:00
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
2009-06-30 06:13:23 +00:00
|
|
|
<!-- _______________________________________________________________________ -->
|
|
|
|
|
<div class="doc_subsubsection">
|
2011-02-20 02:03:04 +00:00
|
|
|
<a name="ll_end">Don't evaluate <tt>end()</tt> every time through a loop</a>
|
2009-06-30 06:13:23 +00:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<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>
|
2009-06-30 06:13:23 +00:00
|
|
|
|
|
|
|
|
<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
|
2009-06-30 06:20:03 +00:00
|
|
|
behavior, please write the loop in the first form and add a comment indicating
|
2009-06-30 06:13:23 +00:00
|
|
|
that you did it intentionally.</p>
|
|
|
|
|
|
|
|
|
|
<p>Why do we prefer the second form (when correct)? Writing the loop in the
|
2010-12-21 03:31:05 +00:00
|
|
|
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
|
2009-06-30 06:13:23 +00:00
|
|
|
expression was actually something like: "<tt>SomeMap[x]->end()</tt>" and map
|
2009-06-30 06:27:54 +00:00
|
|
|
lookups really aren't cheap. By writing it in the second form consistently, you
|
2009-06-30 06:13:23 +00:00
|
|
|
eliminate the issue entirely and don't even have to think about it.</p>
|
|
|
|
|
|
2009-06-30 06:20:03 +00:00
|
|
|
<p>The second (even bigger) issue is that writing the loop in the first form
|
2009-06-30 06:13:23 +00:00
|
|
|
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>
|
|
|
|
|
|
2009-07-22 05:40:54 +00:00
|
|
|
<!-- _______________________________________________________________________ -->
|
|
|
|
|
<div class="doc_subsubsection">
|
2010-12-21 03:31:05 +00:00
|
|
|
<a name="ll_iostream"><tt>#include <iostream></tt> is Forbidden</a>
|
2009-07-22 05:40:54 +00:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
|
|
|
|
|
<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,
|
2010-12-21 03:31:05 +00:00
|
|
|
the static constructors are run whenever an application starts up that uses the
|
|
|
|
|
dynamic library. There are two problems with this:</p>
|
2009-07-22 05:40:54 +00:00
|
|
|
|
|
|
|
|
<ol>
|
2010-12-21 03:31:05 +00:00
|
|
|
<li>The time to run the static c'tors impacts startup time of applications
|
|
|
|
|
— a critical time for GUI apps.</li>
|
|
|
|
|
|
2009-07-22 05:40:54 +00:00
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
<p>Note that using the other stream headers (<tt><sstream></tt> for
|
2010-12-21 03:31:05 +00:00
|
|
|
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
|
2009-08-23 21:53:47 +00:00
|
|
|
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>
|
2009-07-22 05:40:54 +00:00
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
2010-11-17 17:14:55 +00:00
|
|
|
<!-- _______________________________________________________________________ -->
|
|
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="ll_raw_ostream">Use <tt>raw_ostream</tt></a>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
|
|
|
|
|
<p>LLVM includes a lightweight, simple, and efficient stream implementation
|
2010-12-21 03:31:05 +00:00
|
|
|
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>
|
2010-11-17 17:14:55 +00:00
|
|
|
|
|
|
|
|
<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>
|
|
|
|
|
|
|
|
|
|
|
2009-07-22 05:40:54 +00:00
|
|
|
<!-- _______________________________________________________________________ -->
|
|
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="ll_avoidendl">Avoid <tt>std::endl</tt></a>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<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>
|
2009-07-22 05:40:54 +00:00
|
|
|
|
|
|
|
|
<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 class="doc_subsection">
|
|
|
|
|
<a name="nano">Microscopic Details</a>
|
|
|
|
|
</div>
|
|
|
|
|
<!-- ======================================================================= -->
|
|
|
|
|
|
|
|
|
|
<p>This section describes preferred low-level formatting guidelines along with
|
|
|
|
|
reasoning on why we prefer them.</p>
|
|
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
|
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="micro_spaceparen">Spaces Before Parentheses</a>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
|
2010-11-17 17:14:55 +00:00
|
|
|
<p>We prefer to put a space before an open parenthesis only in control flow
|
2009-07-22 05:40:54 +00:00
|
|
|
statements, but not in normal function call expressions and function-like
|
|
|
|
|
macros. For example, this is good:</p>
|
|
|
|
|
|
|
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
2010-12-21 03:31:05 +00:00
|
|
|
<b>if (</b>x) ...
|
|
|
|
|
<b>for (</b>i = 0; i != 100; ++i) ...
|
|
|
|
|
<b>while (</b>llvm_rocks) ...
|
2009-07-22 05:40:54 +00:00
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<b>somefunc(</b>42);
|
|
|
|
|
<b><a href="#ll_assert">assert</a>(</b>3 != 4 && "laws of math are failing me");
|
2009-07-22 05:40:54 +00:00
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
a = <b>foo(</b>42, 92) + <b>bar(</b>x);
|
|
|
|
|
</pre>
|
2009-07-22 05:40:54 +00:00
|
|
|
</div>
|
|
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<p>and this is bad:</p>
|
2009-07-22 05:40:54 +00:00
|
|
|
|
|
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
2010-12-21 03:31:05 +00:00
|
|
|
<b>if(</b>x) ...
|
|
|
|
|
<b>for(</b>i = 0; i != 100; ++i) ...
|
|
|
|
|
<b>while(</b>llvm_rocks) ...
|
2009-07-22 05:40:54 +00:00
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<b>somefunc (</b>42);
|
|
|
|
|
<b><a href="#ll_assert">assert</a> (</b>3 != 4 && "laws of math are failing me");
|
2009-07-22 05:40:54 +00:00
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
a = <b>foo (</b>42, 92) + <b>bar (</b>x);
|
2009-07-22 05:40:54 +00:00
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<p>The reason for doing this is not completely arbitrary. This style makes
|
2010-12-21 03:31:05 +00:00
|
|
|
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>
|
2009-07-22 05:40:54 +00:00
|
|
|
|
|
|
|
|
<div class="doc_code">
|
|
|
|
|
<pre>
|
2010-12-21 03:31:05 +00:00
|
|
|
a = foo <b>(</b>(42, 92) + bar<b>)</b> (x);
|
2009-07-22 05:40:54 +00:00
|
|
|
</pre>
|
|
|
|
|
</div>
|
|
|
|
|
|
2010-12-21 03:31:05 +00:00
|
|
|
<p>when skimming through the code. By avoiding a space in a function, we avoid
|
|
|
|
|
this misinterpretation.</p>
|
2009-07-22 05:40:54 +00:00
|
|
|
|
|
|
|
|
</div>
|
2006-07-27 04:24:14 +00:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
|
|
|
|
<div class="doc_subsubsection">
|
2009-07-22 05:40:54 +00:00
|
|
|
<a name="micro_preincrement">Prefer Preincrement</a>
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2004-07-28 22:31:54 +00:00
|
|
|
<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>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<p>The semantics of postincrement include making a copy of the value being
|
2003-07-28 21:57:18 +00:00
|
|
|
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,
|
2003-10-24 17:57:33 +00:00
|
|
|
get in the habit of always using preincrement, and you won't have a problem.</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2002-01-20 19:01:26 +00:00
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_subsubsection">
|
2009-07-22 05:40:54 +00:00
|
|
|
<a name="micro_namespaceindent">Namespace Indentation</a>
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2002-01-20 19:01:26 +00:00
|
|
|
|
2009-07-22 05:40:54 +00:00
|
|
|
<p>
|
2010-11-17 17:14:55 +00:00
|
|
|
In general, we strive to reduce indentation wherever possible. This is useful
|
2009-07-22 05:40:54 +00:00
|
|
|
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>
|
2002-01-20 19:01:26 +00:00
|
|
|
|
2004-07-28 22:31:54 +00:00
|
|
|
<div class="doc_code">
|
2002-01-20 19:01:26 +00:00
|
|
|
<pre>
|
2009-07-22 16:54:14 +00:00
|
|
|
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
|
|
|
|
|
};
|
|
|
|
|
}
|
2009-07-22 05:40:54 +00:00
|
|
|
}
|
2002-01-20 19:01:26 +00:00
|
|
|
</pre>
|
2004-07-28 22:31:54 +00:00
|
|
|
</div>
|
2002-01-20 19:01:26 +00:00
|
|
|
|
2009-07-22 05:40:54 +00:00
|
|
|
<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
|
2010-11-17 17:14:55 +00:00
|
|
|
larger (as it typically is in a header in the <tt>llvm</tt> or <tt>clang</tt> namespaces), do not
|
2009-07-22 05:40:54 +00:00
|
|
|
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;
|
|
|
|
|
|
|
|
|
|
...
|
2002-01-20 19:01:26 +00:00
|
|
|
|
2009-07-22 05:40:54 +00:00
|
|
|
};
|
|
|
|
|
|
|
|
|
|
} // 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>
|
|
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
|
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="micro_anonns">Anonymous Namespaces</a>
|
2003-10-24 17:57:33 +00:00
|
|
|
</div>
|
2002-01-20 19:01:26 +00:00
|
|
|
|
2009-07-22 05:40:54 +00:00
|
|
|
<div class="doc_text">
|
|
|
|
|
|
2009-07-22 16:54:14 +00:00
|
|
|
<p>After talking about namespaces in general, you may be wondering about
|
|
|
|
|
anonymous namespaces in particular.
|
2009-07-22 05:40:54 +00:00
|
|
|
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
|
2009-07-22 16:54:14 +00:00
|
|
|
namespace just because it was declared there.
|
2009-07-22 05:40:54 +00:00
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
2006-12-09 01:20:34 +00:00
|
|
|
|
2001-07-09 03:27:08 +00:00
|
|
|
<!-- *********************************************************************** -->
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_section">
|
|
|
|
|
<a name="seealso">See Also</a>
|
|
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
2003-10-24 17:57:33 +00:00
|
|
|
<div class="doc_text">
|
|
|
|
|
|
|
|
|
|
<p>A lot of these comments and recommendations have been culled for other
|
|
|
|
|
sources. Two particularly important books for our work are:</p>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
<ol>
|
|
|
|
|
|
2007-11-09 21:49:08 +00:00
|
|
|
<li><a href="http://www.amazon.com/Effective-Specific-Addison-Wesley-Professional-Computing/dp/0321334876">Effective
|
|
|
|
|
C++</a> by Scott Meyers. Also
|
2004-05-23 21:05:07 +00:00
|
|
|
interesting and useful are "More Effective C++" and "Effective STL" by the same
|
|
|
|
|
author.</li>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
2007-11-09 21:49:08 +00:00
|
|
|
<li>Large-Scale C++ Software Design by John Lakos</li>
|
2003-10-24 17:57:33 +00:00
|
|
|
|
|
|
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
<p>If you get some free time, and you haven't read them: do so, you might learn
|
2004-12-04 00:32:12 +00:00
|
|
|
something.</p>
|
2003-10-24 17:57:33 +00:00
|
|
|
|
|
|
|
|
</div>
|
2001-07-09 03:27:08 +00:00
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<hr>
|
2004-05-12 18:37:22 +00:00
|
|
|
<address>
|
|
|
|
|
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
|
2008-12-11 17:34:48 +00:00
|
|
|
src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
|
2004-05-12 18:37:22 +00:00
|
|
|
<a href="http://validator.w3.org/check/referer"><img
|
2008-12-11 17:34:48 +00:00
|
|
|
src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
|
2004-05-12 18:37:22 +00:00
|
|
|
|
|
|
|
|
<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
|
2011-04-09 02:13:37 +00:00
|
|
|
<a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
|
2003-10-24 17:57:33 +00:00
|
|
|
Last modified: $Date$
|
2004-05-12 18:37:22 +00:00
|
|
|
</address>
|
2003-10-24 17:57:33 +00:00
|
|
|
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
