Blame - llvm/docs/CodingStandards.html - toolchain/llvm-project

blob: 7f92b9a7cf0b2047f31b095f0a3ff85622b341d3 [file] [log] [blame]

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