Gitiles
Code Review Sign In
gerrit-public.fairphone.software / fp2-dev / platform / external / llvm / 558f5d2a396c533ddceb9ff278fcb2b76641c0f2 / . / docs / CodingStandards.html
blob: a2420805ec64cf5fecead148baf0cd1deaaf8b15 [file] [log] [blame]
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]1<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
2 "http://www.w3.org/TR/html4/strict.dtd">
3<html>
4<head>
5 <link rel="stylesheet" href="llvm.css" type="text/css">
Misha Brukmanc1449e62008-12-10 23:07:02 +0000[diff] [blame]6 <title>LLVM Coding Standards</title>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]7</head>
8<body>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]9
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]10<div class="doc_title">
Misha Brukmanc1449e62008-12-10 23:07:02 +0000[diff] [blame]11 LLVM Coding Standards
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]12</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]13
14<ol>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]15 <li><a href="#introduction">Introduction</a></li>
Chris Lattner7ae36bb2001-07-23 20:40:41 +0000[diff] [blame]16 <li><a href="#mechanicalissues">Mechanical Source Issues</a>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]17 <ol>
18 <li><a href="#sourceformating">Source Code Formatting</a>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]19 <ol>
20 <li><a href="#scf_commenting">Commenting</a></li>
21 <li><a href="#scf_commentformat">Comment Formatting</a></li>
Misha Brukman91d64af2004-10-26 16:18:43 +0000[diff] [blame]22 <li><a href="#scf_includes"><tt>#include</tt> Style</a></li>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]23 <li><a href="#scf_codewidth">Source Code Width</a></li>
24 <li><a href="#scf_spacestabs">Use Spaces Instead of Tabs</a></li>
25 <li><a href="#scf_indentation">Indent Code Consistently</a></li>
26 </ol></li>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]27 <li><a href="#compilerissues">Compiler Issues</a>
28 <ol>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]29 <li><a href="#ci_warningerrors">Treat Compiler Warnings Like
30 Errors</a></li>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]31 <li><a href="#ci_portable_code">Write Portable Code</a></li>
Chris Lattner558f5d22010-11-30 19:20:40 +0000[diff] [blame^]32 <li><a href="#ci_rtti_exceptions">Do not use RTTI or Exceptions</a></li>
Zhanyong Wancafe0b42010-11-23 05:03:07 +0000[diff] [blame]33 <li><a href="#ci_class_struct">Use of <tt>class</tt>/<tt>struct</tt> Keywords</a></li>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]34 </ol></li>
35 </ol></li>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]36 <li><a href="#styleissues">Style Issues</a>
37 <ol>
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]38 <li><a href="#macro">The High-Level Issues</a>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]39 <ol>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]40 <li><a href="#hl_module">A Public Header File <b>is</b> a
41 Module</a></li>
Zhanyong Wancafe0b42010-11-23 05:03:07 +0000[diff] [blame]42 <li><a href="#hl_dontinclude"><tt>#include</tt> as Little as Possible</a></li>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]43 <li><a href="#hl_privateheaders">Keep "internal" Headers
44 Private</a></li>
Zhanyong Wancafe0b42010-11-23 05:03:07 +0000[diff] [blame]45 <li><a href="#hl_earlyexit">Use Early Exits and <tt>continue</tt> to Simplify
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]46 Code</a></li>
Zhanyong Wancafe0b42010-11-23 05:03:07 +0000[diff] [blame]47 <li><a href="#hl_else_after_return">Don't use <tt>else</tt> after a
48 <tt>return</tt></a></li>
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]49 <li><a href="#hl_predicateloops">Turn Predicate Loops into Predicate
50 Functions</a></li>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]51 </ol></li>
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]52 <li><a href="#micro">The Low-Level Issues</a>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]53 <ol>
Chris Lattner6883a882006-07-27 04:24:14 +0000[diff] [blame]54 <li><a href="#ll_assert">Assert Liberally</a></li>
Zhanyong Wancafe0b42010-11-23 05:03:07 +0000[diff] [blame]55 <li><a href="#ll_ns_std">Do not use '<tt>using namespace std</tt>'</a></li>
Bill Wendling7f564c02006-12-09 01:20:34 +0000[diff] [blame]56 <li><a href="#ll_virtual_anch">Provide a virtual method anchor for
Bill Wendling4ad6d612006-12-09 01:35:43 +0000[diff] [blame]57 classes in headers</a></li>
Zhanyong Wancafe0b42010-11-23 05:03:07 +0000[diff] [blame]58 <li><a href="#ll_end">Don't evaluate <tt>end()</tt> every time through a
Chris Lattner0af39ea2009-06-30 06:13:23 +0000[diff] [blame]59 loop</a></li>
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]60 <li><a href="#ll_iostream"><tt>#include &lt;iostream&gt;</tt> is
61 <em>forbidden</em></a></li>
Daniel Dunbare8530a32009-07-24 23:04:51 +0000[diff] [blame]62 <li><a href="#ll_raw_ostream">Use <tt>raw_ostream</tt></a</li>
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]63 <li><a href="#ll_avoidendl">Avoid <tt>std::endl</tt></a></li>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]64 </ol></li>
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]65
66 <li><a href="#nano">Microscopic Details</a>
67 <ol>
68 <li><a href="#micro_spaceparen">Spaces Before Parentheses</a></li>
69 <li><a href="#micro_preincrement">Prefer Preincrement</a></li>
70 <li><a href="#micro_namespaceindent">Namespace Indentation</a></li>
71 <li><a href="#micro_anonns">Anonymous Namespaces</a></li>
72 </ol></li>
73
74
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]75 </ol></li>
76 <li><a href="#seealso">See Also</a></li>
77</ol>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]78
Chris Lattner999cf092004-05-23 21:05:07 +0000[diff] [blame]79<div class="doc_author">
Chris Lattner219bd292009-07-22 05:43:01 +0000[diff] [blame]80 <p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></p>
Chris Lattner999cf092004-05-23 21:05:07 +0000[diff] [blame]81</div>
82
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]83
84<!-- *********************************************************************** -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]85<div class="doc_section">
86 <a name="introduction">Introduction</a>
87</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]88<!-- *********************************************************************** -->
89
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]90<div class="doc_text">
91
92<p>This document attempts to describe a few coding standards that are being used
93in the LLVM source tree. Although no coding standards should be regarded as
Misha Brukman1b36d672003-10-06 19:26:00 +0000[diff] [blame]94absolute requirements to be followed in all instances, coding standards can be
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]95useful.</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]96
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]97<p>This document intentionally does not prescribe fixed standards for religious
Misha Brukman1b36d672003-10-06 19:26:00 +0000[diff] [blame]98issues such as brace placement and space usage. For issues like this, follow
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]99the golden rule:</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]100
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]101<blockquote>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]102
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]103<p><b><a name="goldenrule">If you are adding a significant body of source to a
104project, feel free to use whatever style you are most comfortable with. If you
105are extending, enhancing, or bug fixing already implemented code, use the style
106that is already being used so that the source is uniform and easy to
107follow.</a></b></p>
108
109</blockquote>
110
111<p>The ultimate goal of these guidelines is the increase readability and
Misha Brukman1b36d672003-10-06 19:26:00 +0000[diff] [blame]112maintainability of our common source base. If you have suggestions for topics to
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]113be included, please mail them to <a
114href="mailto:sabre@nondot.org">Chris</a>.</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]115
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]116</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]117
118<!-- *********************************************************************** -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]119<div class="doc_section">
120 <a name="mechanicalissues">Mechanical Source Issues</a>
121</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]122<!-- *********************************************************************** -->
123
124<!-- ======================================================================= -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]125<div class="doc_subsection">
126 <a name="sourceformating">Source Code Formatting</a>
127</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]128
129<!-- _______________________________________________________________________ -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]130<div class="doc_subsubsection">
131 <a name="scf_commenting">Commenting</a>
132</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]133
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]134<div class="doc_text">
135
136<p>Comments are one critical part of readability and maintainability. Everyone
Chris Lattnerb927ca82009-07-12 00:10:24 +0000[diff] [blame]137knows they should comment, so should you. When writing comments, write them as
138English prose, which means they should use proper capitalization, punctuation,
139etc. Although we all should probably
Misha Brukman1b36d672003-10-06 19:26:00 +0000[diff] [blame]140comment our code more than we do, there are a few very critical places that
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]141documentation is very useful:</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]142
Chris Lattner999cf092004-05-23 21:05:07 +0000[diff] [blame]143<b>File Headers</b>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]144
Reid Spencer669ed452007-07-09 08:04:31 +0000[diff] [blame]145<p>Every source file should have a header on it that describes the basic
146purpose of the file. If a file does not have a header, it should not be
147checked into Subversion. Most source trees will probably have a standard
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]148file header format. The standard format for the LLVM source tree looks like
149this:</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]150
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]151<div class="doc_code">
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]152<pre>
Chris Lattnerc49fcd12003-10-13 14:58:11 +0000[diff] [blame]153//===-- llvm/Instruction.h - Instruction class definition -------*- C++ -*-===//
Misha Brukman98117cd2009-01-02 16:58:42 +0000[diff] [blame]154//
Chris Lattner999cf092004-05-23 21:05:07 +0000[diff] [blame]155// The LLVM Compiler Infrastructure
156//
Chris Lattnerab2b10c2007-12-29 19:56:08 +0000[diff] [blame]157// This file is distributed under the University of Illinois Open Source
158// License. See LICENSE.TXT for details.
Misha Brukman98117cd2009-01-02 16:58:42 +0000[diff] [blame]159//
Chris Lattner999cf092004-05-23 21:05:07 +0000[diff] [blame]160//===----------------------------------------------------------------------===//
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]161//
162// This file contains the declaration of the Instruction class, which is the
163// base class for all of the VM instructions.
164//
165//===----------------------------------------------------------------------===//
166</pre>
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]167</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]168
Chris Lattnerab2b10c2007-12-29 19:56:08 +0000[diff] [blame]169<p>A few things to note about this particular format: The "<tt>-*- C++
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]170-*-</tt>" string on the first line is there to tell Emacs that the source file
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]171is a C++ file, not a C file (Emacs assumes <tt>.h</tt> files are C files by default).
172Note that this tag is not necessary in <tt>.cpp</tt> files. The name of the file is also
Misha Brukman69c58892004-07-28 22:37:57 +0000[diff] [blame]173on the first line, along with a very short description of the purpose of the
174file. This is important when printing out code and flipping though lots of
175pages.</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]176
Chris Lattnerab2b10c2007-12-29 19:56:08 +0000[diff] [blame]177<p>The next section in the file is a concise note that defines the license
178that the file is released under. This makes it perfectly clear what terms the
179source code can be distributed under and should not be modified in any way.</p>
Chris Lattner999cf092004-05-23 21:05:07 +0000[diff] [blame]180
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]181<p>The main body of the description does not have to be very long in most cases.
Misha Brukman1b36d672003-10-06 19:26:00 +0000[diff] [blame]182Here it's only two lines. If an algorithm is being implemented or something
183tricky is going on, a reference to the paper where it is published should be
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]184included, as well as any notes or "gotchas" in the code to watch out for.</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]185
Chris Lattner999cf092004-05-23 21:05:07 +0000[diff] [blame]186<b>Class overviews</b>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]187
Jim Laskeyf55914a2006-07-31 20:18:49 +0000[diff] [blame]188<p>Classes are one fundamental part of a good object oriented design. As such,
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]189a class definition should have a comment block that explains what the class is
Misha Brukman1b36d672003-10-06 19:26:00 +0000[diff] [blame]190used for... if it's not obvious. If it's so completely obvious your grandma
191could figure it out, it's probably safe to leave it out. Naming classes
Misha Brukman3b53a262004-12-04 00:32:12 +0000[diff] [blame]192something sane goes a long ways towards avoiding writing documentation.</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]193
194
Chris Lattner999cf092004-05-23 21:05:07 +0000[diff] [blame]195<b>Method information</b>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]196
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]197<p>Methods defined in a class (as well as any global functions) should also be
Dan Gohman621a4152010-02-26 20:18:32 +0000[diff] [blame]198documented properly. A quick note about what it does and a description of the
Misha Brukman1b36d672003-10-06 19:26:00 +0000[diff] [blame]199borderline behaviour is all that is necessary here (unless something
Dan Gohman621a4152010-02-26 20:18:32 +0000[diff] [blame]200particularly tricky or insidious is going on). The hope is that people can
Misha Brukman1b36d672003-10-06 19:26:00 +0000[diff] [blame]201figure out how to use your interfaces without reading the code itself... that is
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]202the goal metric.</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]203
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]204<p>Good things to talk about here are what happens when something unexpected
205happens: does the method return null? Abort? Format your hard disk?</p>
206
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]207</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]208
209<!-- _______________________________________________________________________ -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]210<div class="doc_subsubsection">
211 <a name="scf_commentformat">Comment Formatting</a>
212</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]213
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]214<div class="doc_text">
215
216<p>In general, prefer C++ style (<tt>//</tt>) comments. They take less space,
Misha Brukman1b36d672003-10-06 19:26:00 +0000[diff] [blame]217require less typing, don't have nesting problems, etc. There are a few cases
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]218when it is useful to use C style (<tt>/* */</tt>) comments however:</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]219
220<ol>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]221 <li>When writing a C code: Obviously if you are writing C code, use C style
Misha Brukman3b53a262004-12-04 00:32:12 +0000[diff] [blame]222 comments.</li>
Misha Brukman91d64af2004-10-26 16:18:43 +0000[diff] [blame]223 <li>When writing a header file that may be <tt>#include</tt>d by a C source
224 file.</li>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]225 <li>When writing a source file that is used by a tool that only accepts C
226 style comments.</li>
227</ol>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]228
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]229<p>To comment out a large block of code, use <tt>#if 0</tt> and <tt>#endif</tt>.
230These nest properly and are better behaved in general than C style comments.</p>
231
232</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]233
Chris Lattner2e5cbc22003-08-07 21:45:47 +0000[diff] [blame]234<!-- _______________________________________________________________________ -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]235<div class="doc_subsubsection">
Misha Brukman91d64af2004-10-26 16:18:43 +0000[diff] [blame]236 <a name="scf_includes"><tt>#include</tt> Style</a>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]237</div>
Chris Lattner2e5cbc22003-08-07 21:45:47 +0000[diff] [blame]238
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]239<div class="doc_text">
240
241<p>Immediately after the <a href="#scf_commenting">header file comment</a> (and
Chris Lattner2e5cbc22003-08-07 21:45:47 +0000[diff] [blame]242include guards if working on a header file), the <a
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]243href="#hl_dontinclude">minimal</a> list of <tt>#include</tt>s required by the
244file should be listed. We prefer these <tt>#include</tt>s to be listed in this
245order:</p>
Chris Lattner2e5cbc22003-08-07 21:45:47 +0000[diff] [blame]246
247<ol>
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]248 <li><a href="#mmheader">Main Module Header</a></li>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]249 <li><a href="#hl_privateheaders">Local/Private Headers</a></li>
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]250 <li><tt>llvm/*</tt></li>
251 <li><tt>llvm/Analysis/*</tt></li>
252 <li><tt>llvm/Assembly/*</tt></li>
Duncan Sands18d52f22010-09-29 20:09:55 +0000[diff] [blame]253 <li><tt>llvm/Bitcode/*</tt></li>
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]254 <li><tt>llvm/CodeGen/*</tt></li>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]255 <li>...</li>
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]256 <li><tt>Support/*</tt></li>
257 <li><tt>Config/*</tt></li>
258 <li>System <tt>#includes</tt></li>
Chris Lattner2e5cbc22003-08-07 21:45:47 +0000[diff] [blame]259</ol>
260
Nick Lewycky822293a2008-11-29 20:13:25 +0000[diff] [blame]261<p>... and each category should be sorted by name.</p>
Chris Lattner2e5cbc22003-08-07 21:45:47 +0000[diff] [blame]262
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]263<p><a name="mmheader">The "Main Module Header"</a> file applies to <tt>.cpp</tt> files
264which implement an interface defined by a <tt>.h</tt> file. This <tt>#include</tt>
Misha Brukman91d64af2004-10-26 16:18:43 +0000[diff] [blame]265should always be included <b>first</b> regardless of where it lives on the file
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]266system. By including a header file first in the <tt>.cpp</tt> files that implement the
Misha Brukman91d64af2004-10-26 16:18:43 +0000[diff] [blame]267interfaces, we ensure that the header does not have any hidden dependencies
268which are not explicitly #included in the header, but should be. It is also a
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]269form of documentation in the <tt>.cpp</tt> file to indicate where the interfaces it
Misha Brukman91d64af2004-10-26 16:18:43 +0000[diff] [blame]270implements are defined.</p>
Chris Lattner2e5cbc22003-08-07 21:45:47 +0000[diff] [blame]271
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]272</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]273
274<!-- _______________________________________________________________________ -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]275<div class="doc_subsubsection">
276 <a name="scf_codewidth">Source Code Width</a>
277</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]278
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]279<div class="doc_text">
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]280
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]281<p>Write your code to fit within 80 columns of text. This helps those of us who
282like to print out code and look at your code in an xterm without resizing
283it.</p>
284
Chris Lattner5822e9e2008-07-08 05:12:37 +0000[diff] [blame]285<p>The longer answer is that there must be some limit to the width of the code
286in order to reasonably allow developers to have multiple files side-by-side in
287windows on a modest display. If you are going to pick a width limit, it is
288somewhat arbitrary but you might as well pick something standard. Going with
28990 columns (for example) instead of 80 columns wouldn't add any significant
290value and would be detrimental to printing out code. Also many other projects
291have standardized on 80 columns, so some people have already configured their
292editors for it (vs something else, like 90 columns).</p>
293
294<p>This is one of many contentious issues in coding standards, but is not up
295for debate.</p>
296
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]297</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]298
299<!-- _______________________________________________________________________ -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]300<div class="doc_subsubsection">
301 <a name="scf_spacestabs">Use Spaces Instead of Tabs</a>
302</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]303
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]304<div class="doc_text">
305
306<p>In all cases, prefer spaces to tabs in source files. People have different
Benjamin Kramer8040cd32009-10-12 14:46:08 +0000[diff] [blame]307preferred indentation levels, and different styles of indentation that they
Misha Brukman1b36d672003-10-06 19:26:00 +0000[diff] [blame]308like... this is fine. What isn't is that different editors/viewers expand tabs
309out to different tab stops. This can cause your code to look completely
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]310unreadable, and it is not worth dealing with.</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]311
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]312<p>As always, follow the <a href="#goldenrule">Golden Rule</a> above: follow the
Misha Brukman1b36d672003-10-06 19:26:00 +0000[diff] [blame]313style of existing code if your are modifying and extending it. If you like four
314spaces of indentation, <b>DO NOT</b> do that in the middle of a chunk of code
315with two spaces of indentation. Also, do not reindent a whole source file: it
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]316makes for incredible diffs that are absolutely worthless.</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]317
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]318</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]319
320<!-- _______________________________________________________________________ -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]321<div class="doc_subsubsection">
322 <a name="scf_indentation">Indent Code Consistently</a>
323</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]324
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]325<div class="doc_text">
326
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]327<p>Okay, in your first year of programming you were told that indentation is
Misha Brukman1b36d672003-10-06 19:26:00 +0000[diff] [blame]328important. If you didn't believe and internalize this then, now is the time.
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]329Just do it.</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]330
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]331</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]332
333
334<!-- ======================================================================= -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]335<div class="doc_subsection">
336 <a name="compilerissues">Compiler Issues</a>
337</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]338
339
340<!-- _______________________________________________________________________ -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]341<div class="doc_subsubsection">
342 <a name="ci_warningerrors">Treat Compiler Warnings Like Errors</a>
343</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]344
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]345<div class="doc_text">
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]346
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]347<p>If your code has compiler warnings in it, something is wrong: you aren't
348casting values correctly, your have "questionable" constructs in your code, or
349you are doing something legitimately wrong. Compiler warnings can cover up
350legitimate errors in output and make dealing with a translation unit
351difficult.</p>
352
353<p>It is not possible to prevent all warnings from all compilers, nor is it
Misha Brukman1b36d672003-10-06 19:26:00 +0000[diff] [blame]354desirable. Instead, pick a standard compiler (like <tt>gcc</tt>) that provides
355a good thorough set of warnings, and stick to them. At least in the case of
356<tt>gcc</tt>, it is possible to work around any spurious errors by changing the
357syntax of the code slightly. For example, an warning that annoys me occurs when
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]358I write code like this:</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]359
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]360<div class="doc_code">
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]361<pre>
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]362if (V = getValue()) {
363 ...
364}
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]365</pre>
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]366</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]367
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]368<p><tt>gcc</tt> will warn me that I probably want to use the <tt>==</tt>
369operator, and that I probably mistyped it. In most cases, I haven't, and I
370really don't want the spurious errors. To fix this particular problem, I
371rewrite the code like this:</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]372
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]373<div class="doc_code">
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]374<pre>
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]375if ((V = getValue())) {
376 ...
377}
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]378</pre>
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]379</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]380
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]381<p>...which shuts <tt>gcc</tt> up. Any <tt>gcc</tt> warning that annoys you can
382be fixed by massaging the code appropriately.</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]383
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]384<p>These are the <tt>gcc</tt> warnings that I prefer to enable: <tt>-Wall
385-Winline -W -Wwrite-strings -Wno-unused</tt></p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]386
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]387</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]388
389<!-- _______________________________________________________________________ -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]390<div class="doc_subsubsection">
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]391 <a name="ci_portable_code">Write Portable Code</a>
392</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]393
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]394<div class="doc_text">
395
396<p>In almost all cases, it is possible and within reason to write completely
Misha Brukman2d10d752003-07-28 21:57:18 +0000[diff] [blame]397portable code. If there are cases where it isn't possible to write portable
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]398code, isolate it behind a well defined (and well documented) interface.</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]399
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]400<p>In practice, this means that you shouldn't assume much about the host
Chris Lattner221b2392010-11-16 22:19:06 +0000[diff] [blame]401compiler, and Visual Studio tends to be the lowest common denominator.
402If advanced features are used, they should only be an implementation detail of
403a library which has a simple exposed API, and preferably be buried in
404libSystem.</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]405
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]406</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]407
Reid Spencerb40df562004-09-23 16:03:48 +0000[diff] [blame]408<!-- _______________________________________________________________________ -->
409<div class="doc_subsubsection">
Chris Lattner558f5d22010-11-30 19:20:40 +0000[diff] [blame^]410<a name="ci_rtti_exceptions">Do not use RTTI or Exceptions</a>
411</div>
412<div class="doc_text">
413
414<p>LLVM does not use RTTI (e.g. dynamic_cast&lt;&gt;) or exceptions, in an
415effort to reduce code and executable size. These two language features violate
416the general C++ principle of "you only pay for what you use", causing executable
417bloat even if exceptions are never used in a code base, or if RTTI is never used
418for a class. Because of this, we turn them off globally in the code.
419</p>
420
421<p>
422That said, LLVM does make extensive use of a hand-rolled form of RTTI that use
423templates like <a href="ProgrammersManual.html#isa">isa&lt;&gt;, cast&lt;&gt;,
424and dyn_cast&lt;&gt;</a>. This form of RTTI is opt-in and can be added to any
425class. It is also substantially more efficient than dynamic_cast&lt;&gt;.
426</p>
427
428</div>
429
430<!-- _______________________________________________________________________ -->
431<div class="doc_subsubsection">
Reid Spencerb40df562004-09-23 16:03:48 +0000[diff] [blame]432<a name="ci_class_struct">Use of <tt>class</tt> and <tt>struct</tt> Keywords</a>
433</div>
434<div class="doc_text">
Misha Brukmanedcc78a2004-10-26 15:45:13 +0000[diff] [blame]435
436<p>In C++, the <tt>class</tt> and <tt>struct</tt> keywords can be used almost
437interchangeably. The only difference is when they are used to declare a class:
438<tt>class</tt> makes all members private by default while <tt>struct</tt> makes
439all members public by default.</p>
440
441<p>Unfortunately, not all compilers follow the rules and some will generate
442different symbols based on whether <tt>class</tt> or <tt>struct</tt> was used to
443declare the symbol. This can lead to problems at link time.</p>
444
445<p>So, the rule for LLVM is to always use the <tt>class</tt> keyword, unless
Chris Lattner57310202009-08-11 17:38:15 +0000[diff] [blame]446<b>all</b> members are public and the type is a C++ "POD" type, in which case
447<tt>struct</tt> is allowed.</p>
Misha Brukmanedcc78a2004-10-26 15:45:13 +0000[diff] [blame]448
Reid Spencerb40df562004-09-23 16:03:48 +0000[diff] [blame]449</div>
450
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]451<!-- *********************************************************************** -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]452<div class="doc_section">
453 <a name="styleissues">Style Issues</a>
454</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]455<!-- *********************************************************************** -->
456
457
458<!-- ======================================================================= -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]459<div class="doc_subsection">
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]460 <a name="macro">The High-Level Issues</a>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]461</div>
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]462<!-- ======================================================================= -->
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]463
464
465<!-- _______________________________________________________________________ -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]466<div class="doc_subsubsection">
467 <a name="hl_module">A Public Header File <b>is</b> a Module</a>
468</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]469
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]470<div class="doc_text">
471
472<p>C++ doesn't do too well in the modularity department. There is no real
Misha Brukman2d10d752003-07-28 21:57:18 +0000[diff] [blame]473encapsulation or data hiding (unless you use expensive protocol classes), but it
474is what we have to work with. When you write a public header file (in the LLVM
475source tree, they live in the top level "include" directory), you are defining a
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]476module of functionality.</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]477
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]478<p>Ideally, modules should be completely independent of each other, and their
Misha Brukman2d10d752003-07-28 21:57:18 +0000[diff] [blame]479header files should only include the absolute minimum number of headers
480possible. A module is not just a class, a function, or a namespace: <a
481href="http://www.cuj.com/articles/2000/0002/0002c/0002c.htm">it's a collection
482of these</a> that defines an interface. This interface may be several
483functions, classes or data structures, but the important issue is how they work
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]484together.</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]485
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]486<p>In general, a module should be implemented with one or more <tt>.cpp</tt>
487files. Each of these <tt>.cpp</tt> files should include the header that defines
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]488their interface first. This ensures that all of the dependences of the module
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]489header have been properly added to the module header itself, and are not
490implicit. System headers should be included after user headers for a
491translation unit.</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]492
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]493</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]494
495<!-- _______________________________________________________________________ -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]496<div class="doc_subsubsection">
Misha Brukman91d64af2004-10-26 16:18:43 +0000[diff] [blame]497 <a name="hl_dontinclude"><tt>#include</tt> as Little as Possible</a>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]498</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]499
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]500<div class="doc_text">
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]501
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]502<p><tt>#include</tt> hurts compile time performance. Don't do it unless you
503have to, especially in header files.</p>
504
505<p>But wait, sometimes you need to have the definition of a class to use it, or
Misha Brukman91d64af2004-10-26 16:18:43 +0000[diff] [blame]506to inherit from it. In these cases go ahead and <tt>#include</tt> that header
507file. Be aware however that there are many cases where you don't need to have
508the full definition of a class. If you are using a pointer or reference to a
509class, you don't need the header file. If you are simply returning a class
510instance from a prototyped function or method, you don't need it. In fact, for
511most cases, you simply don't need the definition of a class... and not
512<tt>#include</tt>'ing speeds up compilation.</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]513
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]514<p>It is easy to try to go too overboard on this recommendation, however. You
Chris Lattner5da59b12007-02-10 18:35:31 +0000[diff] [blame]515<b>must</b> include all of the header files that you are using -- you can
516include them either directly
Misha Brukman2d10d752003-07-28 21:57:18 +0000[diff] [blame]517or indirectly (through another header file). To make sure that you don't
Benjamin Kramer8040cd32009-10-12 14:46:08 +0000[diff] [blame]518accidentally forget to include a header file in your module header, make sure to
Misha Brukman2d10d752003-07-28 21:57:18 +0000[diff] [blame]519include your module header <b>first</b> in the implementation file (as mentioned
520above). This way there won't be any hidden dependencies that you'll find out
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]521about later...</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]522
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]523</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]524
525<!-- _______________________________________________________________________ -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]526<div class="doc_subsubsection">
527 <a name="hl_privateheaders">Keep "internal" Headers Private</a>
528</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]529
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]530<div class="doc_text">
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]531
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]532<p>Many modules have a complex implementation that causes them to use more than
533one implementation (<tt>.cpp</tt>) file. It is often tempting to put the
534internal communication interface (helper classes, extra functions, etc) in the
Misha Brukman3b53a262004-12-04 00:32:12 +0000[diff] [blame]535public module header file. Don't do this.</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]536
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]537<p>If you really need to do something like this, put a private header file in
538the same directory as the source files, and include it locally. This ensures
539that your private interface remains private and undisturbed by outsiders.</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]540
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]541<p>Note however, that it's okay to put extra implementation methods a public
542class itself... just make them private (or protected), and all is well.</p>
543
544</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]545
Bill Wendling7f564c02006-12-09 01:20:34 +0000[diff] [blame]546<!-- _______________________________________________________________________ -->
547<div class="doc_subsubsection">
Zhanyong Wancafe0b42010-11-23 05:03:07 +0000[diff] [blame]548 <a name="hl_earlyexit">Use Early Exits and <tt>continue</tt> to Simplify Code</a>
Bill Wendling7f564c02006-12-09 01:20:34 +0000[diff] [blame]549</div>
550
551<div class="doc_text">
552
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]553<p>When reading code, keep in mind how much state and how many previous
554decisions have to be remembered by the reader to understand a block of code.
555Aim to reduce indentation where possible when it doesn't make it more difficult
556to understand the code. One great way to do this is by making use of early
Zhanyong Wancafe0b42010-11-23 05:03:07 +0000[diff] [blame]557exits and the <tt>continue</tt> keyword in long loops. As an example of using an early
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]558exit from a function, consider this "bad" code:</p>
Bill Wendling7f564c02006-12-09 01:20:34 +0000[diff] [blame]559
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]560<div class="doc_code">
561<pre>
562Value *DoSomething(Instruction *I) {
563 if (!isa&lt;TerminatorInst&gt;(I) &amp;&amp;
564 I-&gt;hasOneUse() &amp;&amp; SomeOtherThing(I)) {
565 ... some long code ....
566 }
567
568 return 0;
569}
570</pre>
571</div>
Bill Wendling7f564c02006-12-09 01:20:34 +0000[diff] [blame]572
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]573<p>This code has several problems if the body of the 'if' is large. When you're
574looking at the top of the function, it isn't immediately clear that this
575<em>only</em> does interesting things with non-terminator instructions, and only
576applies to things with the other predicates. Second, it is relatively difficult
577to describe (in comments) why these predicates are important because the if
578statement makes it difficult to lay out the comments. Third, when you're deep
579within the body of the code, it is indented an extra level. Finally, when
580reading the top of the function, it isn't clear what the result is if the
581predicate isn't true, you have to read to the end of the function to know that
582it returns null.</p>
Matthijs Kooijmaned58a972008-07-30 12:14:10 +0000[diff] [blame]583
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]584<p>It is much preferred to format the code like this:</p>
585
586<div class="doc_code">
587<pre>
588Value *DoSomething(Instruction *I) {
589 // Terminators never need 'something' done to them because, ...
590 if (isa&lt;TerminatorInst&gt;(I))
591 return 0;
592
593 // We conservatively avoid transforming instructions with multiple uses
594 // because goats like cheese.
595 if (!I-&gt;hasOneUse())
596 return 0;
597
598 // This is really just here for example.
599 if (!SomeOtherThing(I))
600 return 0;
601
602 ... some long code ....
603}
604</pre>
605</div>
606
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]607<p>This fixes these problems. A similar problem frequently happens in <tt>for</tt>
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]608loops. A silly example is something like this:</p>
609
610<div class="doc_code">
611<pre>
612 for (BasicBlock::iterator II = BB-&gt;begin(), E = BB-&gt;end(); II != E; ++II) {
613 if (BinaryOperator *BO = dyn_cast&lt;BinaryOperator&gt;(II)) {
614 Value *LHS = BO-&gt;getOperand(0);
615 Value *RHS = BO-&gt;getOperand(1);
616 if (LHS != RHS) {
617 ...
618 }
619 }
620 }
621</pre>
622</div>
623
624<p>When you have very very small loops, this sort of structure is fine, but if
625it exceeds more than 10-15 lines, it becomes difficult for people to read and
626understand at a glance.
627The problem with this sort of code is that it gets very nested very quickly,
628meaning that the reader of the code has to keep a lot of context in their brain
629to remember what is going immediately on in the loop, because they don't know
630if/when the if conditions will have elses etc. It is strongly preferred to
631structure the loop like this:</p>
632
633<div class="doc_code">
634<pre>
635 for (BasicBlock::iterator II = BB-&gt;begin(), E = BB-&gt;end(); II != E; ++II) {
636 BinaryOperator *BO = dyn_cast&lt;BinaryOperator&gt;(II);
637 if (!BO) continue;
638
639 Value *LHS = BO-&gt;getOperand(0);
640 Value *RHS = BO-&gt;getOperand(1);
641 if (LHS == RHS) continue;
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]642 ...
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]643 }
644</pre>
645</div>
646
647<p>This has all the benefits of using early exits from functions: it reduces
648nesting of the loop, it makes it easier to describe why the conditions are true,
Zhanyong Wancafe0b42010-11-23 05:03:07 +0000[diff] [blame]649and it makes it obvious to the reader that there is no <tt>else</tt> coming up that
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]650they have to push context into their brain for. If a loop is large, this can
651be a big understandability win.</p>
652
653</div>
654
Chris Lattner9eb7e0a2009-07-28 22:54:04 +0000[diff] [blame]655<!-- _______________________________________________________________________ -->
656<div class="doc_subsubsection">
Zhanyong Wancafe0b42010-11-23 05:03:07 +0000[diff] [blame]657 <a name="hl_else_after_return">Don't use <tt>else</tt> after a <tt>return</tt></a>
Chris Lattner9eb7e0a2009-07-28 22:54:04 +0000[diff] [blame]658</div>
659
660<div class="doc_text">
661
662<p>For similar reasons above (reduction of indentation and easier reading),
Zhanyong Wancafe0b42010-11-23 05:03:07 +0000[diff] [blame]663 please do not use <tt>else</tt> or '<tt>else if</tt>' after something that interrupts
664 control flow like <tt>return</tt>, <tt>break</tt>, <tt>continue</tt>, <tt>goto</tt>, etc. For example, this is
Chris Lattner9eb7e0a2009-07-28 22:54:04 +0000[diff] [blame]665 "bad":</p>
666
667<div class="doc_code">
668<pre>
669 case 'J': {
670 if (Signed) {
671 Type = Context.getsigjmp_bufType();
672 if (Type.isNull()) {
673 Error = ASTContext::GE_Missing_sigjmp_buf;
674 return QualType();
675 } else {
676 break;
677 }
678 } else {
679 Type = Context.getjmp_bufType();
680 if (Type.isNull()) {
681 Error = ASTContext::GE_Missing_jmp_buf;
682 return QualType();
683 } else {
684 break;
685 }
686 }
687 }
688 }
689</pre>
690</div>
691
692<p>It is better to write this something like:</p>
693
694<div class="doc_code">
695<pre>
696 case 'J':
697 if (Signed) {
698 Type = Context.getsigjmp_bufType();
699 if (Type.isNull()) {
700 Error = ASTContext::GE_Missing_sigjmp_buf;
701 return QualType();
702 }
703 } else {
704 Type = Context.getjmp_bufType();
705 if (Type.isNull()) {
706 Error = ASTContext::GE_Missing_jmp_buf;
707 return QualType();
708 }
709 }
710 break;
711</pre>
712</div>
713
714<p>Or better yet (in this case), as:</p>
715
716<div class="doc_code">
717<pre>
718 case 'J':
719 if (Signed)
720 Type = Context.getsigjmp_bufType();
721 else
722 Type = Context.getjmp_bufType();
723
724 if (Type.isNull()) {
725 Error = Signed ? ASTContext::GE_Missing_sigjmp_buf :
726 ASTContext::GE_Missing_jmp_buf;
727 return QualType();
728 }
729 break;
730</pre>
731</div>
732
733<p>The idea is to reduce indentation and the amount of code you have to keep
734 track of when reading the code.</p>
735
736</div>
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]737
738<!-- _______________________________________________________________________ -->
739<div class="doc_subsubsection">
740 <a name="hl_predicateloops">Turn Predicate Loops into Predicate Functions</a>
741</div>
742
743<div class="doc_text">
744
Chris Lattner59fec6a2009-07-22 16:54:14 +0000[diff] [blame]745<p>It is very common to write small loops that just compute a boolean
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]746 value. There are a number of ways that people commonly write these, but an
747 example of this sort of thing is:</p>
748
749<div class="doc_code">
750<pre>
751 <b>bool FoundFoo = false;</b>
752 for (unsigned i = 0, e = BarList.size(); i != e; ++i)
753 if (BarList[i]-&gt;isFoo()) {
754 <b>FoundFoo = true;</b>
755 break;
756 }
757
758 <b>if (FoundFoo) {</b>
759 ...
760 }
761</pre>
762</div>
763
764<p>This sort of code is awkward to write, and is almost always a bad sign.
765Instead of this sort of loop, we strongly prefer to use a predicate function
766(which may be <a href="#micro_anonns">static</a>) that uses
Chris Lattner59fec6a2009-07-22 16:54:14 +0000[diff] [blame]767<a href="#hl_earlyexit">early exits</a> to compute the predicate. We prefer
768the code to be structured like this:
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]769</p>
770
771
772<div class="doc_code">
773<pre>
774/// ListContainsFoo - Return true if the specified list has an element that is
775/// a foo.
776static bool ListContainsFoo(const std::vector&lt;Bar*&gt; &amp;List) {
777 for (unsigned i = 0, e = List.size(); i != e; ++i)
778 if (List[i]-&gt;isFoo())
779 return true;
780 return false;
781}
782...
783
784 <b>if (ListContainsFoo(BarList)) {</b>
785 ...
786 }
787</pre>
788</div>
789
790<p>There are many reasons for doing this: it reduces indentation and factors out
791code which can often be shared by other code that checks for the same predicate.
792More importantly, it <em>forces you to pick a name</em> for the function, and
793forces you to write a comment for it. In this silly example, this doesn't add
794much value. However, if the condition is complex, this can make it a lot easier
795for the reader to understand the code that queries for this predicate. Instead
Chris Lattner71d8f3b2009-07-22 16:30:39 +0000[diff] [blame]796of being faced with the in-line details of how we check to see if the BarList
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]797contains a foo, we can trust the function name and continue reading with better
798locality.</p>
Bill Wendling7f564c02006-12-09 01:20:34 +0000[diff] [blame]799
800</div>
801
802
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]803<!-- ======================================================================= -->
Chris Lattner999cf092004-05-23 21:05:07 +0000[diff] [blame]804<div class="doc_subsection">
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]805 <a name="micro">The Low-Level Issues</a>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]806</div>
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]807<!-- ======================================================================= -->
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]808
809
810<!-- _______________________________________________________________________ -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]811<div class="doc_subsubsection">
Chris Lattner6883a882006-07-27 04:24:14 +0000[diff] [blame]812 <a name="ll_assert">Assert Liberally</a>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]813</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]814
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]815<div class="doc_text">
816
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]817<p>Use the "<tt>assert</tt>" macro to its fullest. Check all of your
Benjamin Kramer8040cd32009-10-12 14:46:08 +0000[diff] [blame]818preconditions and assumptions, you never know when a bug (not necessarily even
Misha Brukman2d10d752003-07-28 21:57:18 +0000[diff] [blame]819yours) might be caught early by an assertion, which reduces debugging time
820dramatically. The "<tt>&lt;cassert&gt;</tt>" header file is probably already
821included by the header files you are using, so it doesn't cost anything to use
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]822it.</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]823
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]824<p>To further assist with debugging, make sure to put some kind of error message
825in the assertion statement (which is printed if the assertion is tripped). This
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]826helps the poor debugger make sense of why an assertion is being made and
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]827enforced, and hopefully what to do about it. Here is one complete example:</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]828
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]829<div class="doc_code">
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]830<pre>
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]831inline Value *getOperand(unsigned i) {
832 assert(i &lt; Operands.size() &amp;&amp; "getOperand() out of range!");
833 return Operands[i];
834}
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]835</pre>
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]836</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]837
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]838<p>Here are some examples:</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]839
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]840<div class="doc_code">
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]841<pre>
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]842assert(Ty-&gt;isPointerType() &amp;&amp; "Can't allocate a non pointer type!");
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]843
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]844assert((Opcode == Shl || Opcode == Shr) &amp;&amp; "ShiftInst Opcode invalid!");
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]845
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]846assert(idx &lt; getNumSuccessors() &amp;&amp; "Successor # out of range!");
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]847
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]848assert(V1.getType() == V2.getType() &amp;&amp; "Constant types must be identical!");
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]849
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]850assert(isa&lt;PHINode&gt;(Succ-&gt;front()) &amp;&amp; "Only works on PHId BBs!");
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]851</pre>
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]852</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]853
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]854<p>You get the idea...</p>
855
Nick Lewyckyf4408e82008-05-31 23:54:55 +0000[diff] [blame]856<p>Please be aware when adding assert statements that not all compilers are aware of
857the semantics of the assert. In some places, asserts are used to indicate a piece of
858code that should not be reached. These are typically of the form:</p>
859
860<div class="doc_code">
861<pre>
Dan Gohmanf0032762008-11-24 17:18:39 +0000[diff] [blame]862assert(0 &amp;&amp; "Some helpful error message");
Nick Lewyckyf4408e82008-05-31 23:54:55 +0000[diff] [blame]863</pre>
864</div>
865
866<p>When used in a function that returns a value, they should be followed with a return
867statement and a comment indicating that this line is never reached. This will prevent
868a compiler which is unable to deduce that the assert statement never returns from
869generating a warning.</p>
870
871<div class="doc_code">
872<pre>
Dan Gohmanf0032762008-11-24 17:18:39 +0000[diff] [blame]873assert(0 &amp;&amp; "Some helpful error message");
Nick Lewyckyf4408e82008-05-31 23:54:55 +0000[diff] [blame]874// Not reached
875return 0;
876</pre>
877</div>
878
Chris Lattner97928d12010-11-12 00:19:41 +0000[diff] [blame]879<p>Another issue is that values used only by assertions will produce an "unused
880 value" warning when assertions are disabled. For example, this code will warn:
881</p>
882
883<div class="doc_code">
884<pre>
885 unsigned Size = V.size();
886 assert(Size &gt; 42 &amp;&amp; "Vector smaller than it should be");
887
888 bool NewToSet = Myset.insert(Value);
889 assert(NewToSet &amp;&amp; "The value shouldn't be in the set yet");
890</pre>
891</div>
892
893<p>These are two interesting different cases: in the first case, the call to
894V.size() is only useful for the assert, and we don't want it executed when
895assertions are disabled. Code like this should move the call into the assert
896itself. In the second case, the side effects of the call must happen whether
897the assert is enabled or not. In this case, the value should be cast to void
898to disable the warning. To be specific, it is preferred to write the code
899like this:</p>
900
901<div class="doc_code">
902<pre>
903 assert(V.size() &gt; 42 &amp;&amp; "Vector smaller than it should be");
904
905 bool NewToSet = Myset.insert(Value); (void)NewToSet;
906 assert(NewToSet &amp;&amp; "The value shouldn't be in the set yet");
907</pre>
908</div>
909
910
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]911</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]912
Chris Lattnerb0bff9e2006-01-01 21:59:22 +0000[diff] [blame]913<!-- _______________________________________________________________________ -->
914<div class="doc_subsubsection">
Bill Wendling4ad6d612006-12-09 01:35:43 +0000[diff] [blame]915 <a name="ll_ns_std">Do not use '<tt>using namespace std</tt>'</a>
Chris Lattnerb0bff9e2006-01-01 21:59:22 +0000[diff] [blame]916</div>
917
918<div class="doc_text">
919<p>In LLVM, we prefer to explicitly prefix all identifiers from the standard
Bill Wendling4ad6d612006-12-09 01:35:43 +0000[diff] [blame]920namespace with an "<tt>std::</tt>" prefix, rather than rely on
921"<tt>using namespace std;</tt>".</p>
Chris Lattnerb0bff9e2006-01-01 21:59:22 +0000[diff] [blame]922
Bill Wendling4ad6d612006-12-09 01:35:43 +0000[diff] [blame]923<p> In header files, adding a '<tt>using namespace XXX</tt>' directive pollutes
Misha Brukman2d33c542008-12-11 19:37:04 +0000[diff] [blame]924the namespace of any source file that <tt>#include</tt>s the header. This is
925clearly a bad thing.</p>
Chris Lattnerb0bff9e2006-01-01 21:59:22 +0000[diff] [blame]926
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]927<p>In implementation files (e.g. <tt>.cpp</tt> files), the rule is more of a stylistic
Bill Wendling4ad6d612006-12-09 01:35:43 +0000[diff] [blame]928rule, but is still important. Basically, using explicit namespace prefixes
929makes the code <b>clearer</b>, because it is immediately obvious what facilities
930are being used and where they are coming from, and <b>more portable</b>, because
931namespace clashes cannot occur between LLVM code and other namespaces. The
932portability rule is important because different standard library implementations
933expose different symbols (potentially ones they shouldn't), and future revisions
934to the C++ standard will add more symbols to the <tt>std</tt> namespace. As
935such, we never use '<tt>using namespace std;</tt>' in LLVM.</p>
Chris Lattnerb0bff9e2006-01-01 21:59:22 +0000[diff] [blame]936
Bill Wendling4ad6d612006-12-09 01:35:43 +0000[diff] [blame]937<p>The exception to the general rule (i.e. it's not an exception for
938the <tt>std</tt> namespace) is for implementation files. For example, all of
939the code in the LLVM project implements code that lives in the 'llvm' namespace.
Chris Lattnereddd9692010-11-17 19:47:20 +0000[diff] [blame]940As such, it is ok, and actually clearer, for the <tt>.cpp</tt> files to have a
941'<tt>using namespace llvm</tt>' directive at their top, after the
942<tt>#include</tt>s. This reduces indentation in the body of the file for source
943editors that indent based on braces, and keeps the conceptual context cleaner.
944The general form of this rule is that any <tt>.cpp</tt> file that implements
945code in any namespace may use that namespace (and its parents'), but should not
946use any others.</p>
Chris Lattnerb0bff9e2006-01-01 21:59:22 +0000[diff] [blame]947
948</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]949
950<!-- _______________________________________________________________________ -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]951<div class="doc_subsubsection">
Bill Wendling4ad6d612006-12-09 01:35:43 +0000[diff] [blame]952 <a name="ll_virtual_anch">Provide a virtual method anchor for classes
953 in headers</a>
Chris Lattner6883a882006-07-27 04:24:14 +0000[diff] [blame]954</div>
955
956<div class="doc_text">
957
958<p>If a class is defined in a header file and has a v-table (either it has
959virtual methods or it derives from classes with virtual methods), it must
960always have at least one out-of-line virtual method in the class. Without
Misha Brukman2d33c542008-12-11 19:37:04 +0000[diff] [blame]961this, the compiler will copy the vtable and RTTI into every <tt>.o</tt> file
962that <tt>#include</tt>s the header, bloating <tt>.o</tt> file sizes and
963increasing link times.</p>
Chris Lattner6883a882006-07-27 04:24:14 +0000[diff] [blame]964
965</div>
966
Chris Lattner0af39ea2009-06-30 06:13:23 +0000[diff] [blame]967<!-- _______________________________________________________________________ -->
968<div class="doc_subsubsection">
Zhanyong Wancafe0b42010-11-23 05:03:07 +0000[diff] [blame]969 <a name="ll_end">Don't evaluate <tt>end()</tt> every time through a loop</a>
Chris Lattner0af39ea2009-06-30 06:13:23 +0000[diff] [blame]970</div>
971
972<div class="doc_text">
973
974<p>Because C++ doesn't have a standard "foreach" loop (though it can be emulated
975with macros and may be coming in C++'0x) we end up writing a lot of loops that
976manually iterate from begin to end on a variety of containers or through other
977data structures. One common mistake is to write a loop in this style:</p>
978
979<div class="doc_code">
980<pre>
981 BasicBlock *BB = ...
982 for (BasicBlock::iterator I = BB->begin(); I != <b>BB->end()</b>; ++I)
983 ... use I ...
984</pre>
985</div>
986
987<p>The problem with this construct is that it evaluates "<tt>BB->end()</tt>"
988every time through the loop. Instead of writing the loop like this, we strongly
989prefer loops to be written so that they evaluate it once before the loop starts.
990A convenient way to do this is like so:</p>
991
992<div class="doc_code">
993<pre>
994 BasicBlock *BB = ...
995 for (BasicBlock::iterator I = BB->begin(), E = <b>BB->end()</b>; I != E; ++I)
996 ... use I ...
997</pre>
998</div>
999
1000<p>The observant may quickly point out that these two loops may have different
1001semantics: if the container (a basic block in this case) is being mutated, then
1002"<tt>BB->end()</tt>" may change its value every time through the loop and the
1003second loop may not in fact be correct. If you actually do depend on this
Chris Lattner09bc65e2009-06-30 06:20:03 +0000[diff] [blame]1004behavior, please write the loop in the first form and add a comment indicating
Chris Lattner0af39ea2009-06-30 06:13:23 +0000[diff] [blame]1005that you did it intentionally.</p>
1006
1007<p>Why do we prefer the second form (when correct)? Writing the loop in the
1008first form has two problems: First it may be less efficient than evaluating it
1009at the start of the loop. In this case, the cost is probably minor: a few extra
1010loads every time through the loop. However, if the base expression is more
1011complex, then the cost can rise quickly. I've seen loops where the end
1012expression was actually something like: "<tt>SomeMap[x]->end()</tt>" and map
Chris Lattnera44f87f2009-06-30 06:27:54 +0000[diff] [blame]1013lookups really aren't cheap. By writing it in the second form consistently, you
Chris Lattner0af39ea2009-06-30 06:13:23 +0000[diff] [blame]1014eliminate the issue entirely and don't even have to think about it.</p>
1015
Chris Lattner09bc65e2009-06-30 06:20:03 +0000[diff] [blame]1016<p>The second (even bigger) issue is that writing the loop in the first form
Chris Lattner0af39ea2009-06-30 06:13:23 +0000[diff] [blame]1017hints to the reader that the loop is mutating the container (a fact that a
1018comment would handily confirm!). If you write the loop in the second form, it
1019is immediately obvious without even looking at the body of the loop that the
1020container isn't being modified, which makes it easier to read the code and
1021understand what it does.</p>
1022
1023<p>While the second form of the loop is a few extra keystrokes, we do strongly
1024prefer it.</p>
1025
1026</div>
1027
Chris Lattner6883a882006-07-27 04:24:14 +0000[diff] [blame]1028<!-- _______________________________________________________________________ -->
1029<div class="doc_subsubsection">
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]1030 <a name="ll_iostream"><tt>#include &lt;iostream&gt;</tt> is forbidden</a>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]1031</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]1032
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]1033<div class="doc_text">
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]1034
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]1035<p>The use of <tt>#include &lt;iostream&gt;</tt> in library files is
1036hereby <b><em>forbidden</em></b>. The primary reason for doing this is to
1037support clients using LLVM libraries as part of larger systems. In particular,
1038we statically link LLVM into some dynamic libraries. Even if LLVM isn't used,
1039the static c'tors are run whenever an application start up that uses the dynamic
1040library. There are two problems with this:</p>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]1041
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]1042<ol>
1043 <li>The time to run the static c'tors impacts startup time of
1044 applications&mdash;a critical time for GUI apps.</li>
1045 <li>The static c'tors cause the app to pull many extra pages of memory off the
1046 disk: both the code for the static c'tors in each <tt>.o</tt> file and the
1047 small amount of data that gets touched. In addition, touched/dirty pages
1048 put more pressure on the VM system on low-memory machines.</li>
1049</ol>
1050
1051<p>Note that using the other stream headers (<tt>&lt;sstream&gt;</tt> for
Chris Lattner983c5922009-08-23 21:53:47 +0000[diff] [blame]1052example) is not problematic in this regard (just <tt>&lt;iostream&gt;</tt>).
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]1053However, <tt>raw_ostream</tt> provides various APIs that are better performing for almost
1054every use than <tt>std::ostream</tt> style APIs.
1055<b>Therefore new code should always
Chris Lattner983c5922009-08-23 21:53:47 +0000[diff] [blame]1056use <a href="#ll_raw_ostream"><tt>raw_ostream</tt></a> for writing, or
1057the <tt>llvm::MemoryBuffer</tt> API for reading files.</b></p>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]1058
1059</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]1060
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]1061
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]1062<!-- _______________________________________________________________________ -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]1063<div class="doc_subsubsection">
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]1064 <a name="ll_raw_ostream">Use <tt>raw_ostream</tt></a>
1065</div>
1066
1067<div class="doc_text">
1068
1069<p>LLVM includes a lightweight, simple, and efficient stream implementation
1070in <tt>llvm/Support/raw_ostream.h</tt> which provides all of the common features
1071of <tt>std::ostream</tt>. All new code should use <tt>raw_ostream</tt> instead
1072of <tt>ostream</tt>.</p>
1073
1074<p>Unlike <tt>std::ostream</tt>, <tt>raw_ostream</tt> is not a template and can
1075be forward declared as <tt>class raw_ostream</tt>. Public headers should
1076generally not include the <tt>raw_ostream</tt> header, but use forward
1077declarations and constant references to <tt>raw_ostream</tt> instances.</p>
1078
1079</div>
1080
1081
1082<!-- _______________________________________________________________________ -->
1083<div class="doc_subsubsection">
Chris Lattner6883a882006-07-27 04:24:14 +0000[diff] [blame]1084 <a name="ll_avoidendl">Avoid <tt>std::endl</tt></a>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]1085</div>
Chris Lattner13c46592002-01-20 19:01:26 +0000[diff] [blame]1086
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]1087<div class="doc_text">
1088
Chris Lattner999cf092004-05-23 21:05:07 +0000[diff] [blame]1089<p>The <tt>std::endl</tt> modifier, when used with iostreams outputs a newline
1090to the output stream specified. In addition to doing this, however, it also
1091flushes the output stream. In other words, these are equivalent:</p>
Chris Lattner13c46592002-01-20 19:01:26 +0000[diff] [blame]1092
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]1093<div class="doc_code">
Chris Lattner13c46592002-01-20 19:01:26 +0000[diff] [blame]1094<pre>
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]1095std::cout &lt;&lt; std::endl;
1096std::cout &lt;&lt; '\n' &lt;&lt; std::flush;
Chris Lattner13c46592002-01-20 19:01:26 +0000[diff] [blame]1097</pre>
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]1098</div>
Chris Lattner13c46592002-01-20 19:01:26 +0000[diff] [blame]1099
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]1100<p>Most of the time, you probably have no reason to flush the output stream, so
Misha Brukmana8c760a2004-07-28 22:31:54 +0000[diff] [blame]1101it's better to use a literal <tt>'\n'</tt>.</p>
Chris Lattner13c46592002-01-20 19:01:26 +0000[diff] [blame]1102
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]1103</div>
Chris Lattner13c46592002-01-20 19:01:26 +0000[diff] [blame]1104
Bill Wendling7f564c02006-12-09 01:20:34 +0000[diff] [blame]1105
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]1106<!-- ======================================================================= -->
1107<div class="doc_subsection">
1108 <a name="nano">Microscopic Details</a>
1109</div>
1110<!-- ======================================================================= -->
1111
1112<p>This section describes preferred low-level formatting guidelines along with
1113reasoning on why we prefer them.</p>
1114
1115<!-- _______________________________________________________________________ -->
1116<div class="doc_subsubsection">
1117 <a name="micro_spaceparen">Spaces Before Parentheses</a>
1118</div>
1119
1120<div class="doc_text">
1121
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]1122<p>We prefer to put a space before an open parenthesis only in control flow
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]1123statements, but not in normal function call expressions and function-like
1124macros. For example, this is good:</p>
1125
1126<div class="doc_code">
1127<pre>
1128 <b>if (</b>x) ...
1129 <b>for (</b>i = 0; i != 100; ++i) ...
1130 <b>while (</b>llvm_rocks) ...
1131
1132 <b>somefunc(</b>42);
1133 <b><a href="#ll_assert">assert</a>(</b>3 != 4 &amp;&amp; "laws of math are failing me");
1134
1135 a = <b>foo(</b>42, 92) + <b>bar(</b>x);
1136 </pre>
1137</div>
1138
1139<p>... and this is bad:</p>
1140
1141<div class="doc_code">
1142<pre>
1143 <b>if(</b>x) ...
1144 <b>for(</b>i = 0; i != 100; ++i) ...
1145 <b>while(</b>llvm_rocks) ...
1146
1147 <b>somefunc (</b>42);
1148 <b><a href="#ll_assert">assert</a> (</b>3 != 4 &amp;&amp; "laws of math are failing me");
1149
1150 a = <b>foo (</b>42, 92) + <b>bar (</b>x);
1151</pre>
1152</div>
1153
1154<p>The reason for doing this is not completely arbitrary. This style makes
1155 control flow operators stand out more, and makes expressions flow better. The
1156 function call operator binds very tightly as a postfix operator. Putting
1157 a space after a function name (as in the last example) makes it appear that
1158 the code might bind the arguments of the left-hand-side of a binary operator
1159 with the argument list of a function and the name of the right side. More
1160 specifically, it is easy to misread the "a" example as:</p>
1161
1162<div class="doc_code">
1163<pre>
1164 a = foo <b>(</b>(42, 92) + bar<b>)</b> (x);
1165</pre>
1166</div>
1167
1168<p>... when skimming through the code. By avoiding a space in a function, we
1169avoid this misinterpretation.</p>
1170
1171</div>
1172
1173<!-- _______________________________________________________________________ -->
1174<div class="doc_subsubsection">
1175 <a name="micro_preincrement">Prefer Preincrement</a>
1176</div>
1177
1178<div class="doc_text">
1179
1180<p>Hard fast rule: Preincrement (<tt>++X</tt>) may be no slower than
1181postincrement (<tt>X++</tt>) and could very well be a lot faster than it. Use
1182preincrementation whenever possible.</p>
1183
1184<p>The semantics of postincrement include making a copy of the value being
1185incremented, returning it, and then preincrementing the "work value". For
1186primitive types, this isn't a big deal... but for iterators, it can be a huge
1187issue (for example, some iterators contains stack and set objects in them...
1188copying an iterator could invoke the copy ctor's of these as well). In general,
1189get in the habit of always using preincrement, and you won't have a problem.</p>
1190
1191</div>
1192
1193<!-- _______________________________________________________________________ -->
1194<div class="doc_subsubsection">
1195 <a name="micro_namespaceindent">Namespace Indentation</a>
1196</div>
1197
1198<div class="doc_text">
1199
1200<p>
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]1201In general, we strive to reduce indentation wherever possible. This is useful
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]1202because we want code to <a href="#scf_codewidth">fit into 80 columns</a> without
1203wrapping horribly, but also because it makes it easier to understand the code.
1204Namespaces are a funny thing: they are often large, and we often desire to put
1205lots of stuff into them (so they can be large). Other times they are tiny,
1206because they just hold an enum or something similar. In order to balance this,
1207we use different approaches for small versus large namespaces.
1208</p>
1209
1210<p>
1211If a namespace definition is small and <em>easily</em> fits on a screen (say,
1212less than 35 lines of code), then you should indent its body. Here's an
1213example:
1214</p>
1215
1216<div class="doc_code">
1217<pre>
Chris Lattner59fec6a2009-07-22 16:54:14 +0000[diff] [blame]1218namespace llvm {
1219 namespace X86 {
1220 /// RelocationType - An enum for the x86 relocation codes. Note that
1221 /// the terminology here doesn't follow x86 convention - word means
1222 /// 32-bit and dword means 64-bit.
1223 enum RelocationType {
1224 /// reloc_pcrel_word - PC relative relocation, add the relocated value to
1225 /// the value already in memory, after we adjust it for where the PC is.
1226 reloc_pcrel_word = 0,
1227
1228 /// reloc_picrel_word - PIC base relative relocation, add the relocated
1229 /// value to the value already in memory, after we adjust it for where the
1230 /// PIC base is.
1231 reloc_picrel_word = 1,
1232
1233 /// reloc_absolute_word, reloc_absolute_dword - Absolute relocation, just
1234 /// add the relocated value to the value already in memory.
1235 reloc_absolute_word = 2,
1236 reloc_absolute_dword = 3
1237 };
1238 }
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]1239}
1240</pre>
1241</div>
1242
1243<p>Since the body is small, indenting adds value because it makes it very clear
1244where the namespace starts and ends, and it is easy to take the whole thing in
1245in one "gulp" when reading the code. If the blob of code in the namespace is
Chris Lattner684cf812010-11-17 17:14:55 +0000[diff] [blame]1246larger (as it typically is in a header in the <tt>llvm</tt> or <tt>clang</tt> namespaces), do not
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]1247indent the code, and add a comment indicating what namespace is being closed.
1248For example:</p>
1249
1250<div class="doc_code">
1251<pre>
1252namespace llvm {
1253namespace knowledge {
1254
1255/// Grokable - This class represents things that Smith can have an intimate
1256/// understanding of and contains the data associated with it.
1257class Grokable {
1258...
1259public:
1260 explicit Grokable() { ... }
1261 virtual ~Grokable() = 0;
1262
1263 ...
1264
1265};
1266
1267} // end namespace knowledge
1268} // end namespace llvm
1269</pre>
1270</div>
1271
1272<p>Because the class is large, we don't expect that the reader can easily
1273understand the entire concept in a glance, and the end of the file (where the
1274namespaces end) may be a long ways away from the place they open. As such,
1275indenting the contents of the namespace doesn't add any value, and detracts from
1276the readability of the class. In these cases it is best to <em>not</em> indent
1277the contents of the namespace.</p>
1278
1279</div>
1280
1281<!-- _______________________________________________________________________ -->
1282<div class="doc_subsubsection">
1283 <a name="micro_anonns">Anonymous Namespaces</a>
1284</div>
1285
1286<div class="doc_text">
1287
Chris Lattner59fec6a2009-07-22 16:54:14 +0000[diff] [blame]1288<p>After talking about namespaces in general, you may be wondering about
1289anonymous namespaces in particular.
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]1290Anonymous namespaces are a great language feature that tells the C++ compiler
1291that the contents of the namespace are only visible within the current
1292translation unit, allowing more aggressive optimization and eliminating the
1293possibility of symbol name collisions. Anonymous namespaces are to C++ as
1294"static" is to C functions and global variables. While "static" is available
1295in C++, anonymous namespaces are more general: they can make entire classes
1296private to a file.</p>
1297
1298<p>The problem with anonymous namespaces is that they naturally want to
1299encourage indentation of their body, and they reduce locality of reference: if
1300you see a random function definition in a C++ file, it is easy to see if it is
1301marked static, but seeing if it is in an anonymous namespace requires scanning
1302a big chunk of the file.</p>
1303
1304<p>Because of this, we have a simple guideline: make anonymous namespaces as
1305small as possible, and only use them for class declarations. For example, this
1306is good:</p>
1307
1308<div class="doc_code">
1309<pre>
1310<b>namespace {</b>
1311 class StringSort {
1312 ...
1313 public:
1314 StringSort(...)
1315 bool operator&lt;(const char *RHS) const;
1316 };
1317<b>} // end anonymous namespace</b>
1318
1319static void Helper() {
1320 ...
1321}
1322
1323bool StringSort::operator&lt;(const char *RHS) const {
1324 ...
1325}
1326
1327</pre>
1328</div>
1329
1330<p>This is bad:</p>
1331
1332
1333<div class="doc_code">
1334<pre>
1335<b>namespace {</b>
1336class StringSort {
1337...
1338public:
1339 StringSort(...)
1340 bool operator&lt;(const char *RHS) const;
1341};
1342
1343void Helper() {
1344 ...
1345}
1346
1347bool StringSort::operator&lt;(const char *RHS) const {
1348 ...
1349}
1350
1351<b>} // end anonymous namespace</b>
1352
1353</pre>
1354</div>
1355
1356
1357<p>This is bad specifically because if you're looking at "Helper" in the middle
1358of a large C++ file, that you have no immediate way to tell if it is local to
1359the file. When it is marked static explicitly, this is immediately obvious.
1360Also, there is no reason to enclose the definition of "operator&lt;" in the
Chris Lattner59fec6a2009-07-22 16:54:14 +0000[diff] [blame]1361namespace just because it was declared there.
Chris Lattnerd283cb12009-07-22 05:40:54 +0000[diff] [blame]1362</p>
1363
1364</div>
1365
1366
1367
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]1368<!-- *********************************************************************** -->
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]1369<div class="doc_section">
1370 <a name="seealso">See Also</a>
1371</div>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]1372<!-- *********************************************************************** -->
1373
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]1374<div class="doc_text">
1375
1376<p>A lot of these comments and recommendations have been culled for other
1377sources. Two particularly important books for our work are:</p>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]1378
1379<ol>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]1380
Chris Lattner788ee282007-11-09 21:49:08 +0000[diff] [blame]1381<li><a href="http://www.amazon.com/Effective-Specific-Addison-Wesley-Professional-Computing/dp/0321334876">Effective
1382C++</a> by Scott Meyers. Also
Chris Lattner999cf092004-05-23 21:05:07 +0000[diff] [blame]1383interesting and useful are "More Effective C++" and "Effective STL" by the same
1384author.</li>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]1385
Chris Lattner788ee282007-11-09 21:49:08 +0000[diff] [blame]1386<li>Large-Scale C++ Software Design by John Lakos</li>
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]1387
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]1388</ol>
1389
1390<p>If you get some free time, and you haven't read them: do so, you might learn
Misha Brukman3b53a262004-12-04 00:32:12 +0000[diff] [blame]1391something.</p>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]1392
1393</div>
1394
Chris Lattnerd80c43c2001-07-09 03:27:08 +0000[diff] [blame]1395<!-- *********************************************************************** -->
1396
1397<hr>
Misha Brukman6c16c4b2004-05-12 18:37:22 +0000[diff] [blame]1398<address>
1399 <a href="http://jigsaw.w3.org/css-validator/check/referer"><img
Misha Brukman44408702008-12-11 17:34:48 +0000[diff] [blame]1400 src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
Misha Brukman6c16c4b2004-05-12 18:37:22 +0000[diff] [blame]1401 <a href="http://validator.w3.org/check/referer"><img
Misha Brukman44408702008-12-11 17:34:48 +0000[diff] [blame]1402 src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]1403
Misha Brukman6c16c4b2004-05-12 18:37:22 +0000[diff] [blame]1404 <a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
Reid Spencer05fe4b02006-03-14 05:39:39 +0000[diff] [blame]1405 <a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]1406 Last modified: $Date$
Misha Brukman6c16c4b2004-05-12 18:37:22 +0000[diff] [blame]1407</address>
Misha Brukman75f258e2003-10-24 17:57:33 +0000[diff] [blame]1408
1409</body>
1410</html>