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

blob: 11655e01bacebc069742d36993d7e154c18ea18d [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>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	222	<li>When writing 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
Bill Wendling	b860203	2010-12-21 03:31:05 +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
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	295	<p>This is one of many contentious issues in coding standards, but it is not up
Chris Lattner	5822e9e	2008-07-08 05:12:37 +0000	[diff] [blame]	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
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	309	like; this is fine. What isn't fine is that different editors/viewers expand
				310	tabs 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
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	314	style of existing code if you are modifying and extending it. If you like four
Misha Brukman	1b36d67	2003-10-06 19:26:00 +0000	[diff] [blame]	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
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	348	<p>If your code has compiler warnings in it, something is wrong — you
				349	aren't casting values correctly, your have "questionable" constructs in your
				350	code, or you are doing something legitimately wrong. Compiler warnings can
				351	cover up legitimate errors in output and make dealing with a translation unit
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	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
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	356	a good thorough set of warnings, and stick to it. At least in the case of
Misha Brukman	1b36d67	2003-10-06 19:26:00 +0000	[diff] [blame]	357	<tt>gcc</tt>, it is possible to work around any spurious errors by changing the
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	358	syntax of the code slightly. For example, a 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
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	382	<p>which shuts <tt>gcc</tt> up. Any <tt>gcc</tt> warning that annoys you can
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	383	be fixed by massaging the code appropriately.</p>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	384
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	385	<p>These are the <tt>gcc</tt> warnings that I prefer to enable:</p>
				386
				387	<div class="doc_code">
				388	<pre>
				389	-Wall -Winline -W -Wwrite-strings -Wno-unused
				390	</pre>
				391	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	392
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	393	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	394
				395	<!-- _______________________________________________________________________ -->
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	396	<div class="doc_subsubsection">
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	397	<a name="ci_portable_code">Write Portable Code</a>
				398	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	399
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	400	<div class="doc_text">
				401
				402	<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]	403	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]	404	code, isolate it behind a well defined (and well documented) interface.</p>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	405
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	406	<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]	407	compiler, and Visual Studio tends to be the lowest common denominator.
				408	If advanced features are used, they should only be an implementation detail of
				409	a library which has a simple exposed API, and preferably be buried in
				410	libSystem.</p>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	411
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	412	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	413
Reid Spencer	b40df56	2004-09-23 16:03:48 +0000	[diff] [blame]	414	<!-- _______________________________________________________________________ -->
				415	<div class="doc_subsubsection">
Chris Lattner	558f5d2	2010-11-30 19:20:40 +0000	[diff] [blame]	416	<a name="ci_rtti_exceptions">Do not use RTTI or Exceptions</a>
				417	</div>
				418	<div class="doc_text">
				419
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	420	<p>In an effort to reduce code and executable size, LLVM does not use RTTI
				421	(e.g. <tt>dynamic_cast<></tt>) or exceptions. These two language features
				422	violate the general C++ principle of <i>"you only pay for what you use"</i>,
				423	causing executable bloat even if exceptions are never used in the code base, or
				424	if RTTI is never used for a class. Because of this, we turn them off globally
				425	in the code.</p>
Chris Lattner	558f5d2	2010-11-30 19:20:40 +0000	[diff] [blame]	426
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	427	<p>That said, LLVM does make extensive use of a hand-rolled form of RTTI that
				428	use templates like <a href="ProgrammersManual.html#isa"><tt>isa<></tt>,
				429	<tt>cast<></tt>, and <tt>dyn_cast<></tt></a>. This form of RTTI is
				430	opt-in and can be added to any class. It is also substantially more efficient
				431	than <tt>dynamic_cast<></tt>.</p>
Chris Lattner	558f5d2	2010-11-30 19:20:40 +0000	[diff] [blame]	432
				433	</div>
				434
				435	<!-- _______________________________________________________________________ -->
				436	<div class="doc_subsubsection">
Reid Spencer	b40df56	2004-09-23 16:03:48 +0000	[diff] [blame]	437	<a name="ci_class_struct">Use of <tt>class</tt> and <tt>struct</tt> Keywords</a>
				438	</div>
				439	<div class="doc_text">
Misha Brukman	edcc78a	2004-10-26 15:45:13 +0000	[diff] [blame]	440
				441	<p>In C++, the <tt>class</tt> and <tt>struct</tt> keywords can be used almost
				442	interchangeably. The only difference is when they are used to declare a class:
				443	<tt>class</tt> makes all members private by default while <tt>struct</tt> makes
				444	all members public by default.</p>
				445
				446	<p>Unfortunately, not all compilers follow the rules and some will generate
				447	different symbols based on whether <tt>class</tt> or <tt>struct</tt> was used to
				448	declare the symbol. This can lead to problems at link time.</p>
				449
				450	<p>So, the rule for LLVM is to always use the <tt>class</tt> keyword, unless
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	451	<b>all</b> members are public and the type is a C++
				452	<a href="http://en.wikipedia.org/wiki/Plain_old_data_structure">POD</a> type, in
				453	which case <tt>struct</tt> is allowed.</p>
Misha Brukman	edcc78a	2004-10-26 15:45:13 +0000	[diff] [blame]	454
Reid Spencer	b40df56	2004-09-23 16:03:48 +0000	[diff] [blame]	455	</div>
				456
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	457	<!-- *********************************************************************** -->
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	458	<div class="doc_section">
				459	<a name="styleissues">Style Issues</a>
				460	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	461	<!-- *********************************************************************** -->
				462
				463
				464	<!-- ======================================================================= -->
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	465	<div class="doc_subsection">
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	466	<a name="macro">The High-Level Issues</a>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	467	</div>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	468	<!-- ======================================================================= -->
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	469
				470
				471	<!-- _______________________________________________________________________ -->
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	472	<div class="doc_subsubsection">
				473	<a name="hl_module">A Public Header File <b>is</b> a Module</a>
				474	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	475
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	476	<div class="doc_text">
				477
				478	<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]	479	encapsulation or data hiding (unless you use expensive protocol classes), but it
				480	is what we have to work with. When you write a public header file (in the LLVM
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	481	source tree, they live in the top level "<tt>include</tt>" directory), you are
				482	defining a module of functionality.</p>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	483
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	484	<p>Ideally, modules should be completely independent of each other, and their
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	485	header files should only <tt>#include</tt> the absolute minimum number of
				486	headers possible. A module is not just a class, a function, or a
				487	namespace: <a href="http://www.cuj.com/articles/2000/0002/0002c/0002c.htm">it's
				488	a collection of these</a> that defines an interface. This interface may be
				489	several functions, classes, or data structures, but the important issue is how
				490	they work together.</p>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	491
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	492	<p>In general, a module should be implemented by one or more <tt>.cpp</tt>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	493	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]	494	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]	495	header have been properly added to the module header itself, and are not
				496	implicit. System headers should be included after user headers for a
				497	translation unit.</p>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	498
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
				501	<!-- _______________________________________________________________________ -->
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	502	<div class="doc_subsubsection">
Misha Brukman	91d64af	2004-10-26 16:18:43 +0000	[diff] [blame]	503	<a name="hl_dontinclude"><tt>#include</tt> as Little as Possible</a>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	504	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	505
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	506	<div class="doc_text">
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	507
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	508	<p><tt>#include</tt> hurts compile time performance. Don't do it unless you
				509	have to, especially in header files.</p>
				510
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	511	<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]	512	to inherit from it. In these cases go ahead and <tt>#include</tt> that header
				513	file. Be aware however that there are many cases where you don't need to have
				514	the full definition of a class. If you are using a pointer or reference to a
				515	class, you don't need the header file. If you are simply returning a class
				516	instance from a prototyped function or method, you don't need it. In fact, for
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	517	most cases, you simply don't need the definition of a class. And not
Misha Brukman	91d64af	2004-10-26 16:18:43 +0000	[diff] [blame]	518	<tt>#include</tt>'ing speeds up compilation.</p>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	519
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	520	<p>It is easy to try to go too overboard on this recommendation, however. You
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	521	<b>must</b> include all of the header files that you are using — you can
				522	include them either directly or indirectly (through another header file). To
				523	make sure that you don't accidentally forget to include a header file in your
				524	module header, make sure to include your module header <b>first</b> in the
				525	implementation file (as mentioned above). This way there won't be any hidden
				526	dependencies that you'll find out about later.</p>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	527
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	528	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	529
				530	<!-- _______________________________________________________________________ -->
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	531	<div class="doc_subsubsection">
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	532	<a name="hl_privateheaders">Keep "Internal" Headers Private</a>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	533	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	534
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	535	<div class="doc_text">
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	536
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	537	<p>Many modules have a complex implementation that causes them to use more than
				538	one implementation (<tt>.cpp</tt>) file. It is often tempting to put the
				539	internal communication interface (helper classes, extra functions, etc) in the
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	540	public module header file. Don't do this!</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>If you really need to do something like this, put a private header file in
				543	the same directory as the source files, and include it locally. This ensures
				544	that your private interface remains private and undisturbed by outsiders.</p>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	545
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	546	<p>Note however, that it's okay to put extra implementation methods in a public
				547	class itself. Just make them private (or protected) and all is well.</p>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	548
				549	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	550
Bill Wendling	7f564c0	2006-12-09 01:20:34 +0000	[diff] [blame]	551	<!-- _______________________________________________________________________ -->
				552	<div class="doc_subsubsection">
Zhanyong Wan	cafe0b4	2010-11-23 05:03:07 +0000	[diff] [blame]	553	<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]	554	</div>
				555
				556	<div class="doc_text">
				557
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	558	<p>When reading code, keep in mind how much state and how many previous
				559	decisions have to be remembered by the reader to understand a block of code.
				560	Aim to reduce indentation where possible when it doesn't make it more difficult
				561	to understand the code. One great way to do this is by making use of early
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	562	exits and the <tt>continue</tt> keyword in long loops. As an example of using
				563	an early exit from a function, consider this "bad" code:</p>
Bill Wendling	7f564c0	2006-12-09 01:20:34 +0000	[diff] [blame]	564
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	565	<div class="doc_code">
				566	<pre>
				567	Value DoSomething(Instruction I) {
				568	if (!isa<TerminatorInst>(I) &&
				569	I->hasOneUse() && SomeOtherThing(I)) {
				570	... some long code ....
				571	}
				572
				573	return 0;
				574	}
				575	</pre>
				576	</div>
Bill Wendling	7f564c0	2006-12-09 01:20:34 +0000	[diff] [blame]	577
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	578	<p>This code has several problems if the body of the '<tt>if</tt>' is large.
				579	When you're looking at the top of the function, it isn't immediately clear that
				580	this <em>only</em> does interesting things with non-terminator instructions, and
				581	only applies to things with the other predicates. Second, it is relatively
				582	difficult to describe (in comments) why these predicates are important because
				583	the <tt>if</tt> statement makes it difficult to lay out the comments. Third,
				584	when you're deep within the body of the code, it is indented an extra level.
				585	Finally, when reading the top of the function, it isn't clear what the result is
				586	if the predicate isn't true; you have to read to the end of the function to know
				587	that it returns null.</p>
Matthijs Kooijman	ed58a97	2008-07-30 12:14:10 +0000	[diff] [blame]	588
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	589	<p>It is much preferred to format the code like this:</p>
				590
				591	<div class="doc_code">
				592	<pre>
				593	Value DoSomething(Instruction I) {
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	594	// Terminators never need 'something' done to them because ...
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	595	if (isa<TerminatorInst>(I))
				596	return 0;
				597
				598	// We conservatively avoid transforming instructions with multiple uses
				599	// because goats like cheese.
				600	if (!I->hasOneUse())
				601	return 0;
				602
				603	// This is really just here for example.
				604	if (!SomeOtherThing(I))
				605	return 0;
				606
				607	... some long code ....
				608	}
				609	</pre>
				610	</div>
				611
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	612	<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]	613	loops. A silly example is something like this:</p>
				614
				615	<div class="doc_code">
				616	<pre>
				617	for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II != E; ++II) {
				618	if (BinaryOperator *BO = dyn_cast<BinaryOperator>(II)) {
				619	Value *LHS = BO->getOperand(0);
				620	Value *RHS = BO->getOperand(1);
				621	if (LHS != RHS) {
				622	...
				623	}
				624	}
				625	}
				626	</pre>
				627	</div>
				628
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	629	<p>When you have very, very small loops, this sort of structure is fine. But if
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	630	it exceeds more than 10-15 lines, it becomes difficult for people to read and
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	631	understand at a glance. The problem with this sort of code is that it gets very
				632	nested very quickly. Meaning that the reader of the code has to keep a lot of
				633	context in their brain to remember what is going immediately on in the loop,
				634	because they don't know if/when the <tt>if</tt> conditions will have elses etc.
				635	It is strongly preferred to structure the loop like this:</p>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	636
				637	<div class="doc_code">
				638	<pre>
				639	for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II != E; ++II) {
				640	BinaryOperator *BO = dyn_cast<BinaryOperator>(II);
				641	if (!BO) continue;
				642
				643	Value *LHS = BO->getOperand(0);
				644	Value *RHS = BO->getOperand(1);
				645	if (LHS == RHS) continue;
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	646
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	647	...
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	648	}
				649	</pre>
				650	</div>
				651
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	652	<p>This has all the benefits of using early exits for functions: it reduces
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	653	nesting of the loop, it makes it easier to describe why the conditions are true,
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	654	and it makes it obvious to the reader that there is no <tt>else</tt> coming up
				655	that they have to push context into their brain for. If a loop is large, this
				656	can be a big understandability win.</p>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	657
				658	</div>
				659
Chris Lattner	9eb7e0a	2009-07-28 22:54:04 +0000	[diff] [blame]	660	<!-- _______________________________________________________________________ -->
				661	<div class="doc_subsubsection">
Zhanyong Wan	cafe0b4	2010-11-23 05:03:07 +0000	[diff] [blame]	662	<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]	663	</div>
				664
				665	<div class="doc_text">
				666
				667	<p>For similar reasons above (reduction of indentation and easier reading),
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	668	please do not use '<tt>else</tt>' or '<tt>else if</tt>' after something that
				669	interrupts control flow — like <tt>return</tt>, <tt>break</tt>,
				670	<tt>continue</tt>, <tt>goto</tt>, etc. For example, this is <em>bad</em>:</p>
				671
Chris Lattner	9eb7e0a	2009-07-28 22:54:04 +0000	[diff] [blame]	672	<div class="doc_code">
				673	<pre>
				674	case 'J': {
				675	if (Signed) {
				676	Type = Context.getsigjmp_bufType();
				677	if (Type.isNull()) {
				678	Error = ASTContext::GE_Missing_sigjmp_buf;
				679	return QualType();
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	680	<b>} else {
Chris Lattner	9eb7e0a	2009-07-28 22:54:04 +0000	[diff] [blame]	681	break;
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	682	}</b>
Chris Lattner	9eb7e0a	2009-07-28 22:54:04 +0000	[diff] [blame]	683	} else {
				684	Type = Context.getjmp_bufType();
				685	if (Type.isNull()) {
				686	Error = ASTContext::GE_Missing_jmp_buf;
				687	return QualType();
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	688	<b>} else {
Chris Lattner	9eb7e0a	2009-07-28 22:54:04 +0000	[diff] [blame]	689	break;
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	690	}</b>
Chris Lattner	9eb7e0a	2009-07-28 22:54:04 +0000	[diff] [blame]	691	}
				692	}
				693	}
				694	</pre>
				695	</div>
				696
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	697	<p>It is better to write it like this:</p>
Chris Lattner	9eb7e0a	2009-07-28 22:54:04 +0000	[diff] [blame]	698
				699	<div class="doc_code">
				700	<pre>
				701	case 'J':
				702	if (Signed) {
				703	Type = Context.getsigjmp_bufType();
				704	if (Type.isNull()) {
				705	Error = ASTContext::GE_Missing_sigjmp_buf;
				706	return QualType();
				707	}
				708	} else {
				709	Type = Context.getjmp_bufType();
				710	if (Type.isNull()) {
				711	Error = ASTContext::GE_Missing_jmp_buf;
				712	return QualType();
				713	}
				714	}
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	715	<b>break;</b>
Chris Lattner	9eb7e0a	2009-07-28 22:54:04 +0000	[diff] [blame]	716	</pre>
				717	</div>
				718
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	719	<p>Or better yet (in this case) as:</p>
Chris Lattner	9eb7e0a	2009-07-28 22:54:04 +0000	[diff] [blame]	720
				721	<div class="doc_code">
				722	<pre>
				723	case 'J':
				724	if (Signed)
				725	Type = Context.getsigjmp_bufType();
				726	else
				727	Type = Context.getjmp_bufType();
				728
				729	if (Type.isNull()) {
				730	Error = Signed ? ASTContext::GE_Missing_sigjmp_buf :
				731	ASTContext::GE_Missing_jmp_buf;
				732	return QualType();
				733	}
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	734	<b>break;</b>
Chris Lattner	9eb7e0a	2009-07-28 22:54:04 +0000	[diff] [blame]	735	</pre>
				736	</div>
				737
				738	<p>The idea is to reduce indentation and the amount of code you have to keep
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	739	track of when reading the code.</p>
Chris Lattner	9eb7e0a	2009-07-28 22:54:04 +0000	[diff] [blame]	740
				741	</div>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	742
				743	<!-- _______________________________________________________________________ -->
				744	<div class="doc_subsubsection">
				745	<a name="hl_predicateloops">Turn Predicate Loops into Predicate Functions</a>
				746	</div>
				747
				748	<div class="doc_text">
				749
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	750	<p>It is very common to write small loops that just compute a boolean value.
				751	There are a number of ways that people commonly write these, but an example of
				752	this sort of thing is:</p>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	753
				754	<div class="doc_code">
				755	<pre>
				756	<b>bool FoundFoo = false;</b>
				757	for (unsigned i = 0, e = BarList.size(); i != e; ++i)
				758	if (BarList[i]->isFoo()) {
				759	<b>FoundFoo = true;</b>
				760	break;
				761	}
				762
				763	<b>if (FoundFoo) {</b>
				764	...
				765	}
				766	</pre>
				767	</div>
				768
				769	<p>This sort of code is awkward to write, and is almost always a bad sign.
				770	Instead of this sort of loop, we strongly prefer to use a predicate function
				771	(which may be <a href="#micro_anonns">static</a>) that uses
Chris Lattner	59fec6a	2009-07-22 16:54:14 +0000	[diff] [blame]	772	<a href="#hl_earlyexit">early exits</a> to compute the predicate. We prefer
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	773	the code to be structured like this:</p>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	774
				775	<div class="doc_code">
				776	<pre>
				777	/// ListContainsFoo - Return true if the specified list has an element that is
				778	/// a foo.
				779	static bool ListContainsFoo(const std::vector<Bar*> &List) {
				780	for (unsigned i = 0, e = List.size(); i != e; ++i)
				781	if (List[i]->isFoo())
				782	return true;
				783	return false;
				784	}
				785	...
				786
				787	<b>if (ListContainsFoo(BarList)) {</b>
				788	...
				789	}
				790	</pre>
				791	</div>
				792
				793	<p>There are many reasons for doing this: it reduces indentation and factors out
				794	code which can often be shared by other code that checks for the same predicate.
				795	More importantly, it <em>forces you to pick a name</em> for the function, and
				796	forces you to write a comment for it. In this silly example, this doesn't add
				797	much value. However, if the condition is complex, this can make it a lot easier
				798	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]	799	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]	800	contains a foo, we can trust the function name and continue reading with better
				801	locality.</p>
Bill Wendling	7f564c0	2006-12-09 01:20:34 +0000	[diff] [blame]	802
				803	</div>
				804
				805
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	806	<!-- ======================================================================= -->
Chris Lattner	999cf09	2004-05-23 21:05:07 +0000	[diff] [blame]	807	<div class="doc_subsection">
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	808	<a name="micro">The Low-Level Issues</a>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	809	</div>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	810	<!-- ======================================================================= -->
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	811
				812
				813	<!-- _______________________________________________________________________ -->
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	814	<div class="doc_subsubsection">
Zhanyong Wan	7fcd4dc	2010-12-02 05:10:07 +0000	[diff] [blame]	815	<a name="ll_naming">Name Types, Functions, Variables, and Enumerators Properly</a>
				816	</div>
				817
				818	<div class="doc_text">
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	819
				820	<p>Poorly-chosen names can mislead the reader and cause bugs. We cannot stress
				821	enough how important it is to use <em>descriptive</em> names. Pick names that
				822	match the semantics and role of the underlying entities, within reason. Avoid
				823	abbreviations unless they are well known. After picking a good name, make sure
				824	to use consistent capitalization for the name, as inconsistency requires clients
				825	to either memorize the APIs or to look it up to find the exact spelling.</p>
Zhanyong Wan	7fcd4dc	2010-12-02 05:10:07 +0000	[diff] [blame]	826
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	827	<p>In general, names should be in camel case (e.g. <tt>TextFileReader</tt>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	828	and <tt>isLValue()</tt>). Different kinds of declarations have different
				829	rules:</p>
Zhanyong Wan	7fcd4dc	2010-12-02 05:10:07 +0000	[diff] [blame]	830
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	831	<ul>
Chris Lattner	78ceb3a	2010-12-10 00:54:03 +0000	[diff] [blame]	832	<li><p><b>Type names</b> (including classes, structs, enums, typedefs, etc)
				833	should be nouns and start with an upper-case letter (e.g.
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	834	<tt>TextFileReader</tt>).</p></li>
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	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>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	839	or <tt>isFoo()</tt>).</p></li>
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	840
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	841	<li><p><b>Enum declarations</b> (e.g. <tt>enum Foo {...}</tt>) are types, so
				842	they should follow the naming conventions for types. A common use for enums
				843	is as a discriminator for a union, or an indicator of a subclass. When an
				844	enum is used for something like this, it should have a <tt>Kind</tt> suffix
				845	(e.g. <tt>ValueKind</tt>).</p></li>
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	846
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	847	<li><p><b>Enumerators</b> (e.g. <tt>enum { Foo, Bar }</tt>) and <b>public member
				848	variables</b> should start with an upper-case letter, just like types.
				849	Unless the enumerators are defined in their own small namespace or inside a
				850	class, enumerators should have a prefix corresponding to the enum
				851	declaration name. For example, <tt>enum ValueKind { ... };</tt> may contain
				852	enumerators like <tt>VK_Argument</tt>, <tt>VK_BasicBlock</tt>, etc.
				853	Enumerators that are just convenience constants are exempt from the
				854	requirement for a prefix. For instance:</p>
				855
Zhanyong Wan	7fcd4dc	2010-12-02 05:10:07 +0000	[diff] [blame]	856	<div class="doc_code">
				857	<pre>
				858	enum {
				859	MaxSize = 42,
				860	Density = 12
				861	};
				862	</pre>
				863	</div>
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	864	</li>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	865
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	866	</ul>
				867
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	868	<p>As an exception, classes that mimic STL classes can have member names in
				869	STL's style of lower-case words separated by underscores (e.g. <tt>begin()</tt>,
				870	<tt>push_back()</tt>, and <tt>empty()</tt>).</p>
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	871
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	872	<p>Here are some examples of good and bad names:</p>
Zhanyong Wan	7fcd4dc	2010-12-02 05:10:07 +0000	[diff] [blame]	873
Zhanyong Wan	7fcd4dc	2010-12-02 05:10:07 +0000	[diff] [blame]	874	<div class="doc_code">
				875	<pre>
				876	class VehicleMaker {
				877	...
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	878	Factory<Tire> F; // Bad -- abbreviation and non-descriptive.
				879	Factory<Tire> Factory; // Better.
				880	Factory<Tire> TireFactory; // Even better -- if VehicleMaker has more than one
Zhanyong Wan	7fcd4dc	2010-12-02 05:10:07 +0000	[diff] [blame]	881	// kind of factories.
				882	};
				883
				884	Vehicle MakeVehicle(VehicleType Type) {
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	885	VehicleMaker M; // Might be OK if having a short life-span.
				886	Tire tmp1 = M.makeTire(); // Bad -- 'tmp1' provides no information.
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	887	Light headlight = M.makeLight("head"); // Good -- descriptive.
Zhanyong Wan	7fcd4dc	2010-12-02 05:10:07 +0000	[diff] [blame]	888	...
				889	}
				890	</pre>
				891	</div>
				892
				893	</div>
				894
				895
				896	<!-- _______________________________________________________________________ -->
				897	<div class="doc_subsubsection">
Chris Lattner	6883a88	2006-07-27 04:24:14 +0000	[diff] [blame]	898	<a name="ll_assert">Assert Liberally</a>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	899	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	900
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	901	<div class="doc_text">
				902
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	903	<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]	904	preconditions and assumptions, you never know when a bug (not necessarily even
Misha Brukman	2d10d75	2003-07-28 21:57:18 +0000	[diff] [blame]	905	yours) might be caught early by an assertion, which reduces debugging time
				906	dramatically. The "<tt><cassert></tt>" header file is probably already
				907	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]	908	it.</p>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	909
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	910	<p>To further assist with debugging, make sure to put some kind of error message
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	911	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]	912	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]	913	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]	914
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	915	<div class="doc_code">
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	916	<pre>
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	917	inline Value *getOperand(unsigned i) {
				918	assert(i < Operands.size() && "getOperand() out of range!");
				919	return Operands[i];
				920	}
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	921	</pre>
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	922	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	923
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	924	<p>Here are more examples:</p>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	925
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	926	<div class="doc_code">
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	927	<pre>
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	928	assert(Ty->isPointerType() && "Can't allocate a non pointer type!");
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	929
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	930	assert((Opcode == Shl \|\| Opcode == Shr) && "ShiftInst Opcode invalid!");
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(idx < getNumSuccessors() && "Successor # out of range!");
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(V1.getType() == V2.getType() && "Constant types must be identical!");
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(isa<PHINode>(Succ->front()) && "Only works on PHId BBs!");
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	937	</pre>
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	938	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	939
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	940	<p>You get the idea.</p>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	941
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	942	<p>Please be aware that, when adding assert statements, not all compilers are aware of
Nick Lewycky	f4408e8	2008-05-31 23:54:55 +0000	[diff] [blame]	943	the semantics of the assert. In some places, asserts are used to indicate a piece of
				944	code that should not be reached. These are typically of the form:</p>
				945
				946	<div class="doc_code">
				947	<pre>
Dan Gohman	f003276	2008-11-24 17:18:39 +0000	[diff] [blame]	948	assert(0 && "Some helpful error message");
Nick Lewycky	f4408e8	2008-05-31 23:54:55 +0000	[diff] [blame]	949	</pre>
				950	</div>
				951
				952	<p>When used in a function that returns a value, they should be followed with a return
				953	statement and a comment indicating that this line is never reached. This will prevent
				954	a compiler which is unable to deduce that the assert statement never returns from
				955	generating a warning.</p>
				956
				957	<div class="doc_code">
				958	<pre>
Dan Gohman	f003276	2008-11-24 17:18:39 +0000	[diff] [blame]	959	assert(0 && "Some helpful error message");
Nick Lewycky	f4408e8	2008-05-31 23:54:55 +0000	[diff] [blame]	960	// Not reached
				961	return 0;
				962	</pre>
				963	</div>
				964
Chris Lattner	97928d1	2010-11-12 00:19:41 +0000	[diff] [blame]	965	<p>Another issue is that values used only by assertions will produce an "unused
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	966	value" warning when assertions are disabled. For example, this code will
				967	warn:</p>
Chris Lattner	97928d1	2010-11-12 00:19:41 +0000	[diff] [blame]	968
				969	<div class="doc_code">
				970	<pre>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	971	unsigned Size = V.size();
				972	assert(Size > 42 && "Vector smaller than it should be");
Chris Lattner	97928d1	2010-11-12 00:19:41 +0000	[diff] [blame]	973
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	974	bool NewToSet = Myset.insert(Value);
				975	assert(NewToSet && "The value shouldn't be in the set yet");
Chris Lattner	97928d1	2010-11-12 00:19:41 +0000	[diff] [blame]	976	</pre>
				977	</div>
				978
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	979	<p>These are two interesting different cases. In the first case, the call to
Chris Lattner	97928d1	2010-11-12 00:19:41 +0000	[diff] [blame]	980	V.size() is only useful for the assert, and we don't want it executed when
				981	assertions are disabled. Code like this should move the call into the assert
				982	itself. In the second case, the side effects of the call must happen whether
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	983	the assert is enabled or not. In this case, the value should be cast to void to
				984	disable the warning. To be specific, it is preferred to write the code like
				985	this:</p>
Chris Lattner	97928d1	2010-11-12 00:19:41 +0000	[diff] [blame]	986
				987	<div class="doc_code">
				988	<pre>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	989	assert(V.size() > 42 && "Vector smaller than it should be");
Chris Lattner	97928d1	2010-11-12 00:19:41 +0000	[diff] [blame]	990
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	991	bool NewToSet = Myset.insert(Value); (void)NewToSet;
				992	assert(NewToSet && "The value shouldn't be in the set yet");
Chris Lattner	97928d1	2010-11-12 00:19:41 +0000	[diff] [blame]	993	</pre>
				994	</div>
				995
				996
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	997	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	998
Chris Lattner	b0bff9e	2006-01-01 21:59:22 +0000	[diff] [blame]	999	<!-- _______________________________________________________________________ -->
				1000	<div class="doc_subsubsection">
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1001	<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]	1002	</div>
				1003
				1004	<div class="doc_text">
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1005
Chris Lattner	b0bff9e	2006-01-01 21:59:22 +0000	[diff] [blame]	1006	<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]	1007	namespace with an "<tt>std::</tt>" prefix, rather than rely on
				1008	"<tt>using namespace std;</tt>".</p>
Chris Lattner	b0bff9e	2006-01-01 21:59:22 +0000	[diff] [blame]	1009
Bill Wendling	4ad6d61	2006-12-09 01:35:43 +0000	[diff] [blame]	1010	<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]	1011	the namespace of any source file that <tt>#include</tt>s the header. This is
				1012	clearly a bad thing.</p>
Chris Lattner	b0bff9e	2006-01-01 21:59:22 +0000	[diff] [blame]	1013
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	1014	<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]	1015	rule, but is still important. Basically, using explicit namespace prefixes
				1016	makes the code <b>clearer</b>, because it is immediately obvious what facilities
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1017	are being used and where they are coming from. And <b>more portable</b>, because
Bill Wendling	4ad6d61	2006-12-09 01:35:43 +0000	[diff] [blame]	1018	namespace clashes cannot occur between LLVM code and other namespaces. The
				1019	portability rule is important because different standard library implementations
				1020	expose different symbols (potentially ones they shouldn't), and future revisions
				1021	to the C++ standard will add more symbols to the <tt>std</tt> namespace. As
				1022	such, we never use '<tt>using namespace std;</tt>' in LLVM.</p>
Chris Lattner	b0bff9e	2006-01-01 21:59:22 +0000	[diff] [blame]	1023
Bill Wendling	4ad6d61	2006-12-09 01:35:43 +0000	[diff] [blame]	1024	<p>The exception to the general rule (i.e. it's not an exception for
				1025	the <tt>std</tt> namespace) is for implementation files. For example, all of
				1026	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]	1027	As such, it is ok, and actually clearer, for the <tt>.cpp</tt> files to have a
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1028	'<tt>using namespace llvm;</tt>' directive at the top, after the
Chris Lattner	eddd969	2010-11-17 19:47:20 +0000	[diff] [blame]	1029	<tt>#include</tt>s. This reduces indentation in the body of the file for source
				1030	editors that indent based on braces, and keeps the conceptual context cleaner.
				1031	The general form of this rule is that any <tt>.cpp</tt> file that implements
				1032	code in any namespace may use that namespace (and its parents'), but should not
				1033	use any others.</p>
Chris Lattner	b0bff9e	2006-01-01 21:59:22 +0000	[diff] [blame]	1034
				1035	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1036
				1037	<!-- _______________________________________________________________________ -->
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1038	<div class="doc_subsubsection">
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1039	<a name="ll_virtual_anch">Provide a Virtual Method Anchor for Classes
				1040	in Headers</a>
Chris Lattner	6883a88	2006-07-27 04:24:14 +0000	[diff] [blame]	1041	</div>
				1042
				1043	<div class="doc_text">
				1044
				1045	<p>If a class is defined in a header file and has a v-table (either it has
				1046	virtual methods or it derives from classes with virtual methods), it must
				1047	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]	1048	this, the compiler will copy the vtable and RTTI into every <tt>.o</tt> file
				1049	that <tt>#include</tt>s the header, bloating <tt>.o</tt> file sizes and
				1050	increasing link times.</p>
Chris Lattner	6883a88	2006-07-27 04:24:14 +0000	[diff] [blame]	1051
				1052	</div>
				1053
Chris Lattner	0af39ea	2009-06-30 06:13:23 +0000	[diff] [blame]	1054	<!-- _______________________________________________________________________ -->
				1055	<div class="doc_subsubsection">
Nick Lewycky	7ac0199	2011-02-20 02:03:04 +0000	[diff] [blame]	1056	<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]	1057	</div>
				1058
				1059	<div class="doc_text">
				1060
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1061	<p>Because C++ doesn't have a standard "<tt>foreach</tt>" loop (though it can be
				1062	emulated with macros and may be coming in C++'0x) we end up writing a lot of
				1063	loops that manually iterate from begin to end on a variety of containers or
				1064	through other data structures. One common mistake is to write a loop in this
				1065	style:</p>
Chris Lattner	0af39ea	2009-06-30 06:13:23 +0000	[diff] [blame]	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
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	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
				1098	few extra loads every time through the loop. However, if the base expression is
				1099	more complex, then the cost can rise quickly. I've seen loops where the end
Chris Lattner	0af39ea	2009-06-30 06:13:23 +0000	[diff] [blame]	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">
Bill Wendling	b860203	2010-12-21 03:31:05 +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,
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1127	the static constructors are run whenever an application starts up that uses the
				1128	dynamic 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>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1131	<li>The time to run the static c'tors impacts startup time of applications
				1132	— a critical time for GUI apps.</li>
				1133
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1134	<li>The static c'tors cause the app to pull many extra pages of memory off the
				1135	disk: both the code for the static c'tors in each <tt>.o</tt> file and the
				1136	small amount of data that gets touched. In addition, touched/dirty pages
				1137	put more pressure on the VM system on low-memory machines.</li>
				1138	</ol>
				1139
				1140	<p>Note that using the other stream headers (<tt><sstream></tt> for
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1141	example) is not problematic in this regard —
				1142	just <tt><iostream></tt>. However, <tt>raw_ostream</tt> provides various
				1143	APIs that are better performing for almost every use than <tt>std::ostream</tt>
				1144	style APIs. <b>Therefore new code should always
Chris Lattner	983c592	2009-08-23 21:53:47 +0000	[diff] [blame]	1145	use <a href="#ll_raw_ostream"><tt>raw_ostream</tt></a> for writing, or
				1146	the <tt>llvm::MemoryBuffer</tt> API for reading files.</b></p>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1147
				1148	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1149
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1150
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1151	<!-- _______________________________________________________________________ -->
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1152	<div class="doc_subsubsection">
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	1153	<a name="ll_raw_ostream">Use <tt>raw_ostream</tt></a>
				1154	</div>
				1155
				1156	<div class="doc_text">
				1157
				1158	<p>LLVM includes a lightweight, simple, and efficient stream implementation
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1159	in <tt>llvm/Support/raw_ostream.h</tt>, which provides all of the common
				1160	features of <tt>std::ostream</tt>. All new code should use <tt>raw_ostream</tt>
				1161	instead of <tt>ostream</tt>.</p>
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	1162
				1163	<p>Unlike <tt>std::ostream</tt>, <tt>raw_ostream</tt> is not a template and can
				1164	be forward declared as <tt>class raw_ostream</tt>. Public headers should
				1165	generally not include the <tt>raw_ostream</tt> header, but use forward
				1166	declarations and constant references to <tt>raw_ostream</tt> instances.</p>
				1167
				1168	</div>
				1169
				1170
				1171	<!-- _______________________________________________________________________ -->
				1172	<div class="doc_subsubsection">
Chris Lattner	6883a88	2006-07-27 04:24:14 +0000	[diff] [blame]	1173	<a name="ll_avoidendl">Avoid <tt>std::endl</tt></a>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1174	</div>
Chris Lattner	13c4659	2002-01-20 19:01:26 +0000	[diff] [blame]	1175
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1176	<div class="doc_text">
				1177
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1178	<p>The <tt>std::endl</tt> modifier, when used with <tt>iostreams</tt> outputs a
				1179	newline to the output stream specified. In addition to doing this, however, it
				1180	also flushes the output stream. In other words, these are equivalent:</p>
Chris Lattner	13c4659	2002-01-20 19:01:26 +0000	[diff] [blame]	1181
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	1182	<div class="doc_code">
Chris Lattner	13c4659	2002-01-20 19:01:26 +0000	[diff] [blame]	1183	<pre>
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	1184	std::cout << std::endl;
				1185	std::cout << '\n' << std::flush;
Chris Lattner	13c4659	2002-01-20 19:01:26 +0000	[diff] [blame]	1186	</pre>
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	1187	</div>
Chris Lattner	13c4659	2002-01-20 19:01:26 +0000	[diff] [blame]	1188
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1189	<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]	1190	it's better to use a literal <tt>'\n'</tt>.</p>
Chris Lattner	13c4659	2002-01-20 19:01:26 +0000	[diff] [blame]	1191
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1192	</div>
Chris Lattner	13c4659	2002-01-20 19:01:26 +0000	[diff] [blame]	1193
Bill Wendling	7f564c0	2006-12-09 01:20:34 +0000	[diff] [blame]	1194
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1195	<!-- ======================================================================= -->
				1196	<div class="doc_subsection">
				1197	<a name="nano">Microscopic Details</a>
				1198	</div>
				1199	<!-- ======================================================================= -->
				1200
				1201	<p>This section describes preferred low-level formatting guidelines along with
				1202	reasoning on why we prefer them.</p>
				1203
				1204	<!-- _______________________________________________________________________ -->
				1205	<div class="doc_subsubsection">
				1206	<a name="micro_spaceparen">Spaces Before Parentheses</a>
				1207	</div>
				1208
				1209	<div class="doc_text">
				1210
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	1211	<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]	1212	statements, but not in normal function call expressions and function-like
				1213	macros. For example, this is good:</p>
				1214
				1215	<div class="doc_code">
				1216	<pre>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1217	<b>if (</b>x) ...
				1218	<b>for (</b>i = 0; i != 100; ++i) ...
				1219	<b>while (</b>llvm_rocks) ...
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1220
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1221	<b>somefunc(</b>42);
				1222	<b><a href="#ll_assert">assert</a>(</b>3 != 4 && "laws of math are failing me");
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1223
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1224	a = <b>foo(</b>42, 92) + <b>bar(</b>x);
				1225	</pre>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1226	</div>
				1227
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1228	<p>and this is bad:</p>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1229
				1230	<div class="doc_code">
				1231	<pre>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1232	<b>if(</b>x) ...
				1233	<b>for(</b>i = 0; i != 100; ++i) ...
				1234	<b>while(</b>llvm_rocks) ...
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1235
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1236	<b>somefunc (</b>42);
				1237	<b><a href="#ll_assert">assert</a> (</b>3 != 4 && "laws of math are failing me");
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1238
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1239	a = <b>foo (</b>42, 92) + <b>bar (</b>x);
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1240	</pre>
				1241	</div>
				1242
				1243	<p>The reason for doing this is not completely arbitrary. This style makes
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1244	control flow operators stand out more, and makes expressions flow better. The
				1245	function call operator binds very tightly as a postfix operator. Putting a
				1246	space after a function name (as in the last example) makes it appear that the
				1247	code might bind the arguments of the left-hand-side of a binary operator with
				1248	the argument list of a function and the name of the right side. More
				1249	specifically, it is easy to misread the "a" example as:</p>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1250
				1251	<div class="doc_code">
				1252	<pre>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1253	a = foo <b>(</b>(42, 92) + bar<b>)</b> (x);
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1254	</pre>
				1255	</div>
				1256
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1257	<p>when skimming through the code. By avoiding a space in a function, we avoid
				1258	this misinterpretation.</p>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1259
				1260	</div>
				1261
				1262	<!-- _______________________________________________________________________ -->
				1263	<div class="doc_subsubsection">
				1264	<a name="micro_preincrement">Prefer Preincrement</a>
				1265	</div>
				1266
				1267	<div class="doc_text">
				1268
				1269	<p>Hard fast rule: Preincrement (<tt>++X</tt>) may be no slower than
				1270	postincrement (<tt>X++</tt>) and could very well be a lot faster than it. Use
				1271	preincrementation whenever possible.</p>
				1272
				1273	<p>The semantics of postincrement include making a copy of the value being
				1274	incremented, returning it, and then preincrementing the "work value". For
				1275	primitive types, this isn't a big deal... but for iterators, it can be a huge
				1276	issue (for example, some iterators contains stack and set objects in them...
				1277	copying an iterator could invoke the copy ctor's of these as well). In general,
				1278	get in the habit of always using preincrement, and you won't have a problem.</p>
				1279
				1280	</div>
				1281
				1282	<!-- _______________________________________________________________________ -->
				1283	<div class="doc_subsubsection">
				1284	<a name="micro_namespaceindent">Namespace Indentation</a>
				1285	</div>
				1286
				1287	<div class="doc_text">
				1288
				1289	<p>
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	1290	In general, we strive to reduce indentation wherever possible. This is useful
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1291	because we want code to <a href="#scf_codewidth">fit into 80 columns</a> without
				1292	wrapping horribly, but also because it makes it easier to understand the code.
				1293	Namespaces are a funny thing: they are often large, and we often desire to put
				1294	lots of stuff into them (so they can be large). Other times they are tiny,
				1295	because they just hold an enum or something similar. In order to balance this,
				1296	we use different approaches for small versus large namespaces.
				1297	</p>
				1298
				1299	<p>
				1300	If a namespace definition is small and <em>easily</em> fits on a screen (say,
				1301	less than 35 lines of code), then you should indent its body. Here's an
				1302	example:
				1303	</p>
				1304
				1305	<div class="doc_code">
				1306	<pre>
Chris Lattner	59fec6a	2009-07-22 16:54:14 +0000	[diff] [blame]	1307	namespace llvm {
				1308	namespace X86 {
				1309	/// RelocationType - An enum for the x86 relocation codes. Note that
				1310	/// the terminology here doesn't follow x86 convention - word means
				1311	/// 32-bit and dword means 64-bit.
				1312	enum RelocationType {
				1313	/// reloc_pcrel_word - PC relative relocation, add the relocated value to
				1314	/// the value already in memory, after we adjust it for where the PC is.
				1315	reloc_pcrel_word = 0,
				1316
				1317	/// reloc_picrel_word - PIC base relative relocation, add the relocated
				1318	/// value to the value already in memory, after we adjust it for where the
				1319	/// PIC base is.
				1320	reloc_picrel_word = 1,
				1321
				1322	/// reloc_absolute_word, reloc_absolute_dword - Absolute relocation, just
				1323	/// add the relocated value to the value already in memory.
				1324	reloc_absolute_word = 2,
				1325	reloc_absolute_dword = 3
				1326	};
				1327	}
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1328	}
				1329	</pre>
				1330	</div>
				1331
				1332	<p>Since the body is small, indenting adds value because it makes it very clear
				1333	where the namespace starts and ends, and it is easy to take the whole thing in
				1334	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]	1335	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]	1336	indent the code, and add a comment indicating what namespace is being closed.
				1337	For example:</p>
				1338
				1339	<div class="doc_code">
				1340	<pre>
				1341	namespace llvm {
				1342	namespace knowledge {
				1343
				1344	/// Grokable - This class represents things that Smith can have an intimate
				1345	/// understanding of and contains the data associated with it.
				1346	class Grokable {
				1347	...
				1348	public:
				1349	explicit Grokable() { ... }
				1350	virtual ~Grokable() = 0;
				1351
				1352	...
				1353
				1354	};
				1355
				1356	} // end namespace knowledge
				1357	} // end namespace llvm
				1358	</pre>
				1359	</div>
				1360
				1361	<p>Because the class is large, we don't expect that the reader can easily
				1362	understand the entire concept in a glance, and the end of the file (where the
				1363	namespaces end) may be a long ways away from the place they open. As such,
				1364	indenting the contents of the namespace doesn't add any value, and detracts from
				1365	the readability of the class. In these cases it is best to <em>not</em> indent
				1366	the contents of the namespace.</p>
				1367
				1368	</div>
				1369
				1370	<!-- _______________________________________________________________________ -->
				1371	<div class="doc_subsubsection">
				1372	<a name="micro_anonns">Anonymous Namespaces</a>
				1373	</div>
				1374
				1375	<div class="doc_text">
				1376
Chris Lattner	59fec6a	2009-07-22 16:54:14 +0000	[diff] [blame]	1377	<p>After talking about namespaces in general, you may be wondering about
				1378	anonymous namespaces in particular.
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1379	Anonymous namespaces are a great language feature that tells the C++ compiler
				1380	that the contents of the namespace are only visible within the current
				1381	translation unit, allowing more aggressive optimization and eliminating the
				1382	possibility of symbol name collisions. Anonymous namespaces are to C++ as
				1383	"static" is to C functions and global variables. While "static" is available
				1384	in C++, anonymous namespaces are more general: they can make entire classes
				1385	private to a file.</p>
				1386
				1387	<p>The problem with anonymous namespaces is that they naturally want to
				1388	encourage indentation of their body, and they reduce locality of reference: if
				1389	you see a random function definition in a C++ file, it is easy to see if it is
				1390	marked static, but seeing if it is in an anonymous namespace requires scanning
				1391	a big chunk of the file.</p>
				1392
				1393	<p>Because of this, we have a simple guideline: make anonymous namespaces as
				1394	small as possible, and only use them for class declarations. For example, this
				1395	is good:</p>
				1396
				1397	<div class="doc_code">
				1398	<pre>
				1399	<b>namespace {</b>
				1400	class StringSort {
				1401	...
				1402	public:
				1403	StringSort(...)
				1404	bool operator<(const char *RHS) const;
				1405	};
				1406	<b>} // end anonymous namespace</b>
				1407
				1408	static void Helper() {
				1409	...
				1410	}
				1411
				1412	bool StringSort::operator<(const char *RHS) const {
				1413	...
				1414	}
				1415
				1416	</pre>
				1417	</div>
				1418
				1419	<p>This is bad:</p>
				1420
				1421
				1422	<div class="doc_code">
				1423	<pre>
				1424	<b>namespace {</b>
				1425	class StringSort {
				1426	...
				1427	public:
				1428	StringSort(...)
				1429	bool operator<(const char *RHS) const;
				1430	};
				1431
				1432	void Helper() {
				1433	...
				1434	}
				1435
				1436	bool StringSort::operator<(const char *RHS) const {
				1437	...
				1438	}
				1439
				1440	<b>} // end anonymous namespace</b>
				1441
				1442	</pre>
				1443	</div>
				1444
				1445
				1446	<p>This is bad specifically because if you're looking at "Helper" in the middle
				1447	of a large C++ file, that you have no immediate way to tell if it is local to
				1448	the file. When it is marked static explicitly, this is immediately obvious.
				1449	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]	1450	namespace just because it was declared there.
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1451	</p>
				1452
				1453	</div>
				1454
				1455
				1456
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1457	<!-- *********************************************************************** -->
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1458	<div class="doc_section">
				1459	<a name="seealso">See Also</a>
				1460	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1461	<!-- *********************************************************************** -->
				1462
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1463	<div class="doc_text">
				1464
				1465	<p>A lot of these comments and recommendations have been culled for other
				1466	sources. Two particularly important books for our work are:</p>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1467
				1468	<ol>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1469
Chris Lattner	788ee28	2007-11-09 21:49:08 +0000	[diff] [blame]	1470	<li><a href="http://www.amazon.com/Effective-Specific-Addison-Wesley-Professional-Computing/dp/0321334876">Effective
				1471	C++</a> by Scott Meyers. Also
Chris Lattner	999cf09	2004-05-23 21:05:07 +0000	[diff] [blame]	1472	interesting and useful are "More Effective C++" and "Effective STL" by the same
				1473	author.</li>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1474
Chris Lattner	788ee28	2007-11-09 21:49:08 +0000	[diff] [blame]	1475	<li>Large-Scale C++ Software Design by John Lakos</li>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1476
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1477	</ol>
				1478
				1479	<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]	1480	something.</p>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1481
				1482	</div>
				1483
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1484	<!-- *********************************************************************** -->
				1485
				1486	<hr>
Misha Brukman	6c16c4b	2004-05-12 18:37:22 +0000	[diff] [blame]	1487	<address>
				1488	<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
Misha Brukman	4440870	2008-12-11 17:34:48 +0000	[diff] [blame]	1489	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]	1490	<a href="http://validator.w3.org/check/referer"><img
Misha Brukman	4440870	2008-12-11 17:34:48 +0000	[diff] [blame]	1491	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]	1492
Misha Brukman	6c16c4b	2004-05-12 18:37:22 +0000	[diff] [blame]	1493	<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
NAKAMURA Takumi	b9a3363	2011-04-09 02:13:37 +0000	[diff] [blame^]	1494	<a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1495	Last modified: $Date$
Misha Brukman	6c16c4b	2004-05-12 18:37:22 +0000	[diff] [blame]	1496	</address>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1497
				1498	</body>
				1499	</html>