Blame - docs/CodingStandards.html - platform/external/llvm

blob: ff33ffa98a94b1f3ed3ba4ddde87383609548925 [file] [log] [blame]

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