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