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

blob: ca31cab2ca094089bd9bf395400c5bba6b826e2e [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
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	10	<h1>
Misha Brukman	c1449e6	2008-12-10 23:07:02 +0000	[diff] [blame]	11	LLVM Coding Standards
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	12	</h1>
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	<!-- *********************************************************************** -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	86	<h2>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	87	<a name="introduction">Introduction</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	88	</h2>
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	<!-- *********************************************************************** -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	120	<h2>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	121	<a name="mechanicalissues">Mechanical Source Issues</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	122	</h2>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	123	<!-- *********************************************************************** -->
				124
				125	<!-- ======================================================================= -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	126	<h3>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	127	<a name="sourceformating">Source Code Formatting</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	128	</h3>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	129
				130	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	131	<h4>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	132	<a name="scf_commenting">Commenting</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	133	</h4>
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	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	211	<h4>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	212	<a name="scf_commentformat">Comment Formatting</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	213	</h4>
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	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	236	<h4>
Misha Brukman	91d64af	2004-10-26 16:18:43 +0000	[diff] [blame]	237	<a name="scf_includes"><tt>#include</tt> Style</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	238	</h4>
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	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	276	<h4>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	277	<a name="scf_codewidth">Source Code Width</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	278	</h4>
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	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	301	<h4>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	302	<a name="scf_spacestabs">Use Spaces Instead of Tabs</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	303	</h4>
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	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	322	<h4>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	323	<a name="scf_indentation">Indent Code Consistently</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	324	</h4>
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	<!-- ======================================================================= -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	336	<h3>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	337	<a name="compilerissues">Compiler Issues</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	338	</h3>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	339
				340
				341	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	342	<h4>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	343	<a name="ci_warningerrors">Treat Compiler Warnings Like Errors</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	344	</h4>
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	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	396	<h4>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	397	<a name="ci_portable_code">Write Portable Code</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	398	</h4>
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	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	415	<h4>
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>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	417	</h4>
Chris Lattner	558f5d2	2010-11-30 19:20:40 +0000	[diff] [blame]	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	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	436	<h4>
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>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	438	</h4>
Reid Spencer	b40df56	2004-09-23 16:03:48 +0000	[diff] [blame]	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	<!-- *********************************************************************** -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	458	<h2>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	459	<a name="styleissues">Style Issues</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	460	</h2>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	461	<!-- *********************************************************************** -->
				462
				463
				464	<!-- ======================================================================= -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	465	<h3>
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	466	<a name="macro">The High-Level Issues</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	467	</h3>
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	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	472	<h4>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	473	<a name="hl_module">A Public Header File <b>is</b> a Module</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	474	</h4>
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	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	502	<h4>
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>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	504	</h4>
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	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	531	<h4>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	532	<a name="hl_privateheaders">Keep "Internal" Headers Private</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	533	</h4>
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	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	552	<h4>
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>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	554	</h4>
Bill Wendling	7f564c0	2006-12-09 01:20:34 +0000	[diff] [blame]	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	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	661	<h4>
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>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	663	</h4>
Chris Lattner	9eb7e0a	2009-07-28 22:54:04 +0000	[diff] [blame]	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	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	744	<h4>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	745	<a name="hl_predicateloops">Turn Predicate Loops into Predicate Functions</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	746	</h4>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	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	<!-- ======================================================================= -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	807	<h3>
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	808	<a name="micro">The Low-Level Issues</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	809	</h3>
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	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	814	<h4>
				815	<a name="ll_naming">
				816	Name Types, Functions, Variables, and Enumerators Properly
				817	</a>
				818	</h4>
Zhanyong Wan	7fcd4dc	2010-12-02 05:10:07 +0000	[diff] [blame]	819
				820	<div class="doc_text">
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	821
				822	<p>Poorly-chosen names can mislead the reader and cause bugs. We cannot stress
				823	enough how important it is to use <em>descriptive</em> names. Pick names that
				824	match the semantics and role of the underlying entities, within reason. Avoid
				825	abbreviations unless they are well known. After picking a good name, make sure
				826	to use consistent capitalization for the name, as inconsistency requires clients
				827	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]	828
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	829	<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]	830	and <tt>isLValue()</tt>). Different kinds of declarations have different
				831	rules:</p>
Zhanyong Wan	7fcd4dc	2010-12-02 05:10:07 +0000	[diff] [blame]	832
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	833	<ul>
Chris Lattner	78ceb3a	2010-12-10 00:54:03 +0000	[diff] [blame]	834	<li><p><b>Type names</b> (including classes, structs, enums, typedefs, etc)
				835	should be nouns and start with an upper-case letter (e.g.
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	836	<tt>TextFileReader</tt>).</p></li>
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	837
Chris Lattner	78ceb3a	2010-12-10 00:54:03 +0000	[diff] [blame]	838	<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]	839	actions), and command-like function should be imperative. The name should
				840	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]	841	or <tt>isFoo()</tt>).</p></li>
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	842
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	843	<li><p><b>Enum declarations</b> (e.g. <tt>enum Foo {...}</tt>) are types, so
				844	they should follow the naming conventions for types. A common use for enums
				845	is as a discriminator for a union, or an indicator of a subclass. When an
				846	enum is used for something like this, it should have a <tt>Kind</tt> suffix
				847	(e.g. <tt>ValueKind</tt>).</p></li>
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	848
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	849	<li><p><b>Enumerators</b> (e.g. <tt>enum { Foo, Bar }</tt>) and <b>public member
				850	variables</b> should start with an upper-case letter, just like types.
				851	Unless the enumerators are defined in their own small namespace or inside a
				852	class, enumerators should have a prefix corresponding to the enum
				853	declaration name. For example, <tt>enum ValueKind { ... };</tt> may contain
				854	enumerators like <tt>VK_Argument</tt>, <tt>VK_BasicBlock</tt>, etc.
				855	Enumerators that are just convenience constants are exempt from the
				856	requirement for a prefix. For instance:</p>
				857
Zhanyong Wan	7fcd4dc	2010-12-02 05:10:07 +0000	[diff] [blame]	858	<div class="doc_code">
				859	<pre>
				860	enum {
				861	MaxSize = 42,
				862	Density = 12
				863	};
				864	</pre>
				865	</div>
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	866	</li>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	867
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	868	</ul>
				869
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	870	<p>As an exception, classes that mimic STL classes can have member names in
				871	STL's style of lower-case words separated by underscores (e.g. <tt>begin()</tt>,
				872	<tt>push_back()</tt>, and <tt>empty()</tt>).</p>
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	873
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	874	<p>Here are some examples of good and bad names:</p>
Zhanyong Wan	7fcd4dc	2010-12-02 05:10:07 +0000	[diff] [blame]	875
Zhanyong Wan	7fcd4dc	2010-12-02 05:10:07 +0000	[diff] [blame]	876	<div class="doc_code">
				877	<pre>
				878	class VehicleMaker {
				879	...
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	880	Factory<Tire> F; // Bad -- abbreviation and non-descriptive.
				881	Factory<Tire> Factory; // Better.
				882	Factory<Tire> TireFactory; // Even better -- if VehicleMaker has more than one
Zhanyong Wan	7fcd4dc	2010-12-02 05:10:07 +0000	[diff] [blame]	883	// kind of factories.
				884	};
				885
				886	Vehicle MakeVehicle(VehicleType Type) {
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	887	VehicleMaker M; // Might be OK if having a short life-span.
				888	Tire tmp1 = M.makeTire(); // Bad -- 'tmp1' provides no information.
Chris Lattner	69ad797	2010-12-10 00:52:35 +0000	[diff] [blame]	889	Light headlight = M.makeLight("head"); // Good -- descriptive.
Zhanyong Wan	7fcd4dc	2010-12-02 05:10:07 +0000	[diff] [blame]	890	...
				891	}
				892	</pre>
				893	</div>
				894
				895	</div>
				896
				897
				898	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	899	<h4>
Chris Lattner	6883a88	2006-07-27 04:24:14 +0000	[diff] [blame]	900	<a name="ll_assert">Assert Liberally</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	901	</h4>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	902
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	903	<div class="doc_text">
				904
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	905	<p>Use the "<tt>assert</tt>" macro to its fullest. Check all of your
Benjamin Kramer	8040cd3	2009-10-12 14:46:08 +0000	[diff] [blame]	906	preconditions and assumptions, you never know when a bug (not necessarily even
Misha Brukman	2d10d75	2003-07-28 21:57:18 +0000	[diff] [blame]	907	yours) might be caught early by an assertion, which reduces debugging time
				908	dramatically. The "<tt><cassert></tt>" header file is probably already
				909	included by the header files you are using, so it doesn't cost anything to use
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	910	it.</p>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	911
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	912	<p>To further assist with debugging, make sure to put some kind of error message
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	913	in the assertion statement, which is printed if the assertion is tripped. This
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	914	helps the poor debugger make sense of why an assertion is being made and
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	915	enforced, and hopefully what to do about it. Here is one complete example:</p>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	916
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	917	<div class="doc_code">
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	918	<pre>
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	919	inline Value *getOperand(unsigned i) {
				920	assert(i < Operands.size() && "getOperand() out of range!");
				921	return Operands[i];
				922	}
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	923	</pre>
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	924	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	925
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	926	<p>Here are more examples:</p>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	927
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	928	<div class="doc_code">
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	929	<pre>
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	930	assert(Ty->isPointerType() && "Can't allocate a non pointer type!");
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	931
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	932	assert((Opcode == Shl \|\| Opcode == Shr) && "ShiftInst Opcode invalid!");
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	933
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	934	assert(idx < getNumSuccessors() && "Successor # out of range!");
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	935
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	936	assert(V1.getType() == V2.getType() && "Constant types must be identical!");
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	937
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	938	assert(isa<PHINode>(Succ->front()) && "Only works on PHId BBs!");
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	939	</pre>
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	940	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	941
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	942	<p>You get the idea.</p>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	943
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	944	<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]	945	the semantics of the assert. In some places, asserts are used to indicate a piece of
				946	code that should not be reached. These are typically of the form:</p>
				947
				948	<div class="doc_code">
				949	<pre>
Dan Gohman	f003276	2008-11-24 17:18:39 +0000	[diff] [blame]	950	assert(0 && "Some helpful error message");
Nick Lewycky	f4408e8	2008-05-31 23:54:55 +0000	[diff] [blame]	951	</pre>
				952	</div>
				953
				954	<p>When used in a function that returns a value, they should be followed with a return
				955	statement and a comment indicating that this line is never reached. This will prevent
				956	a compiler which is unable to deduce that the assert statement never returns from
				957	generating a warning.</p>
				958
				959	<div class="doc_code">
				960	<pre>
Dan Gohman	f003276	2008-11-24 17:18:39 +0000	[diff] [blame]	961	assert(0 && "Some helpful error message");
Nick Lewycky	f4408e8	2008-05-31 23:54:55 +0000	[diff] [blame]	962	// Not reached
				963	return 0;
				964	</pre>
				965	</div>
				966
Chris Lattner	97928d1	2010-11-12 00:19:41 +0000	[diff] [blame]	967	<p>Another issue is that values used only by assertions will produce an "unused
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	968	value" warning when assertions are disabled. For example, this code will
				969	warn:</p>
Chris Lattner	97928d1	2010-11-12 00:19:41 +0000	[diff] [blame]	970
				971	<div class="doc_code">
				972	<pre>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	973	unsigned Size = V.size();
				974	assert(Size > 42 && "Vector smaller than it should be");
Chris Lattner	97928d1	2010-11-12 00:19:41 +0000	[diff] [blame]	975
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	976	bool NewToSet = Myset.insert(Value);
				977	assert(NewToSet && "The value shouldn't be in the set yet");
Chris Lattner	97928d1	2010-11-12 00:19:41 +0000	[diff] [blame]	978	</pre>
				979	</div>
				980
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	981	<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]	982	V.size() is only useful for the assert, and we don't want it executed when
				983	assertions are disabled. Code like this should move the call into the assert
				984	itself. In the second case, the side effects of the call must happen whether
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	985	the assert is enabled or not. In this case, the value should be cast to void to
				986	disable the warning. To be specific, it is preferred to write the code like
				987	this:</p>
Chris Lattner	97928d1	2010-11-12 00:19:41 +0000	[diff] [blame]	988
				989	<div class="doc_code">
				990	<pre>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	991	assert(V.size() > 42 && "Vector smaller than it should be");
Chris Lattner	97928d1	2010-11-12 00:19:41 +0000	[diff] [blame]	992
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	993	bool NewToSet = Myset.insert(Value); (void)NewToSet;
				994	assert(NewToSet && "The value shouldn't be in the set yet");
Chris Lattner	97928d1	2010-11-12 00:19:41 +0000	[diff] [blame]	995	</pre>
				996	</div>
				997
				998
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	999	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1000
Chris Lattner	b0bff9e	2006-01-01 21:59:22 +0000	[diff] [blame]	1001	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1002	<h4>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1003	<a name="ll_ns_std">Do Not Use '<tt>using namespace std</tt>'</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1004	</h4>
Chris Lattner	b0bff9e	2006-01-01 21:59:22 +0000	[diff] [blame]	1005
				1006	<div class="doc_text">
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1007
Chris Lattner	b0bff9e	2006-01-01 21:59:22 +0000	[diff] [blame]	1008	<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]	1009	namespace with an "<tt>std::</tt>" prefix, rather than rely on
				1010	"<tt>using namespace std;</tt>".</p>
Chris Lattner	b0bff9e	2006-01-01 21:59:22 +0000	[diff] [blame]	1011
Bill Wendling	4ad6d61	2006-12-09 01:35:43 +0000	[diff] [blame]	1012	<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]	1013	the namespace of any source file that <tt>#include</tt>s the header. This is
				1014	clearly a bad thing.</p>
Chris Lattner	b0bff9e	2006-01-01 21:59:22 +0000	[diff] [blame]	1015
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	1016	<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]	1017	rule, but is still important. Basically, using explicit namespace prefixes
				1018	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]	1019	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]	1020	namespace clashes cannot occur between LLVM code and other namespaces. The
				1021	portability rule is important because different standard library implementations
				1022	expose different symbols (potentially ones they shouldn't), and future revisions
				1023	to the C++ standard will add more symbols to the <tt>std</tt> namespace. As
				1024	such, we never use '<tt>using namespace std;</tt>' in LLVM.</p>
Chris Lattner	b0bff9e	2006-01-01 21:59:22 +0000	[diff] [blame]	1025
Bill Wendling	4ad6d61	2006-12-09 01:35:43 +0000	[diff] [blame]	1026	<p>The exception to the general rule (i.e. it's not an exception for
				1027	the <tt>std</tt> namespace) is for implementation files. For example, all of
				1028	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]	1029	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]	1030	'<tt>using namespace llvm;</tt>' directive at the top, after the
Chris Lattner	eddd969	2010-11-17 19:47:20 +0000	[diff] [blame]	1031	<tt>#include</tt>s. This reduces indentation in the body of the file for source
				1032	editors that indent based on braces, and keeps the conceptual context cleaner.
				1033	The general form of this rule is that any <tt>.cpp</tt> file that implements
				1034	code in any namespace may use that namespace (and its parents'), but should not
				1035	use any others.</p>
Chris Lattner	b0bff9e	2006-01-01 21:59:22 +0000	[diff] [blame]	1036
				1037	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1038
				1039	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1040	<h4>
				1041	<a name="ll_virtual_anch">
				1042	Provide a Virtual Method Anchor for Classes in Headers
				1043	</a>
				1044	</h4>
Chris Lattner	6883a88	2006-07-27 04:24:14 +0000	[diff] [blame]	1045
				1046	<div class="doc_text">
				1047
				1048	<p>If a class is defined in a header file and has a v-table (either it has
				1049	virtual methods or it derives from classes with virtual methods), it must
				1050	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]	1051	this, the compiler will copy the vtable and RTTI into every <tt>.o</tt> file
				1052	that <tt>#include</tt>s the header, bloating <tt>.o</tt> file sizes and
				1053	increasing link times.</p>
Chris Lattner	6883a88	2006-07-27 04:24:14 +0000	[diff] [blame]	1054
				1055	</div>
				1056
Chris Lattner	0af39ea	2009-06-30 06:13:23 +0000	[diff] [blame]	1057	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1058	<h4>
Nick Lewycky	7ac0199	2011-02-20 02:03:04 +0000	[diff] [blame]	1059	<a name="ll_end">Don't evaluate <tt>end()</tt> every time through a loop</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1060	</h4>
Chris Lattner	0af39ea	2009-06-30 06:13:23 +0000	[diff] [blame]	1061
				1062	<div class="doc_text">
				1063
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1064	<p>Because C++ doesn't have a standard "<tt>foreach</tt>" loop (though it can be
				1065	emulated with macros and may be coming in C++'0x) we end up writing a lot of
				1066	loops that manually iterate from begin to end on a variety of containers or
				1067	through other data structures. One common mistake is to write a loop in this
				1068	style:</p>
Chris Lattner	0af39ea	2009-06-30 06:13:23 +0000	[diff] [blame]	1069
				1070	<div class="doc_code">
				1071	<pre>
				1072	BasicBlock *BB = ...
				1073	for (BasicBlock::iterator I = BB->begin(); I != <b>BB->end()</b>; ++I)
				1074	... use I ...
				1075	</pre>
				1076	</div>
				1077
				1078	<p>The problem with this construct is that it evaluates "<tt>BB->end()</tt>"
				1079	every time through the loop. Instead of writing the loop like this, we strongly
				1080	prefer loops to be written so that they evaluate it once before the loop starts.
				1081	A convenient way to do this is like so:</p>
				1082
				1083	<div class="doc_code">
				1084	<pre>
				1085	BasicBlock *BB = ...
				1086	for (BasicBlock::iterator I = BB->begin(), E = <b>BB->end()</b>; I != E; ++I)
				1087	... use I ...
				1088	</pre>
				1089	</div>
				1090
				1091	<p>The observant may quickly point out that these two loops may have different
				1092	semantics: if the container (a basic block in this case) is being mutated, then
				1093	"<tt>BB->end()</tt>" may change its value every time through the loop and the
				1094	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]	1095	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]	1096	that you did it intentionally.</p>
				1097
				1098	<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]	1099	first form has two problems. First it may be less efficient than evaluating it
				1100	at the start of the loop. In this case, the cost is probably minor — a
				1101	few extra loads every time through the loop. However, if the base expression is
				1102	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]	1103	expression was actually something like: "<tt>SomeMap[x]->end()</tt>" and map
Chris Lattner	a44f87f	2009-06-30 06:27:54 +0000	[diff] [blame]	1104	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]	1105	eliminate the issue entirely and don't even have to think about it.</p>
				1106
Chris Lattner	09bc65e	2009-06-30 06:20:03 +0000	[diff] [blame]	1107	<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]	1108	hints to the reader that the loop is mutating the container (a fact that a
				1109	comment would handily confirm!). If you write the loop in the second form, it
				1110	is immediately obvious without even looking at the body of the loop that the
				1111	container isn't being modified, which makes it easier to read the code and
				1112	understand what it does.</p>
				1113
				1114	<p>While the second form of the loop is a few extra keystrokes, we do strongly
				1115	prefer it.</p>
				1116
				1117	</div>
				1118
Chris Lattner	6883a88	2006-07-27 04:24:14 +0000	[diff] [blame]	1119	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1120	<h4>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1121	<a name="ll_iostream"><tt>#include <iostream></tt> is Forbidden</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1122	</h4>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1123
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1124	<div class="doc_text">
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1125
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1126	<p>The use of <tt>#include <iostream></tt> in library files is
				1127	hereby <b><em>forbidden</em></b>. The primary reason for doing this is to
				1128	support clients using LLVM libraries as part of larger systems. In particular,
				1129	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]	1130	the static constructors are run whenever an application starts up that uses the
				1131	dynamic library. There are two problems with this:</p>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1132
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1133	<ol>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1134	<li>The time to run the static c'tors impacts startup time of applications
				1135	— a critical time for GUI apps.</li>
				1136
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1137	<li>The static c'tors cause the app to pull many extra pages of memory off the
				1138	disk: both the code for the static c'tors in each <tt>.o</tt> file and the
				1139	small amount of data that gets touched. In addition, touched/dirty pages
				1140	put more pressure on the VM system on low-memory machines.</li>
				1141	</ol>
				1142
				1143	<p>Note that using the other stream headers (<tt><sstream></tt> for
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1144	example) is not problematic in this regard —
				1145	just <tt><iostream></tt>. However, <tt>raw_ostream</tt> provides various
				1146	APIs that are better performing for almost every use than <tt>std::ostream</tt>
				1147	style APIs. <b>Therefore new code should always
Chris Lattner	983c592	2009-08-23 21:53:47 +0000	[diff] [blame]	1148	use <a href="#ll_raw_ostream"><tt>raw_ostream</tt></a> for writing, or
				1149	the <tt>llvm::MemoryBuffer</tt> API for reading files.</b></p>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1150
				1151	</div>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1152
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1153
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1154	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1155	<h4>
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	1156	<a name="ll_raw_ostream">Use <tt>raw_ostream</tt></a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1157	</h4>
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	1158
				1159	<div class="doc_text">
				1160
				1161	<p>LLVM includes a lightweight, simple, and efficient stream implementation
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1162	in <tt>llvm/Support/raw_ostream.h</tt>, which provides all of the common
				1163	features of <tt>std::ostream</tt>. All new code should use <tt>raw_ostream</tt>
				1164	instead of <tt>ostream</tt>.</p>
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	1165
				1166	<p>Unlike <tt>std::ostream</tt>, <tt>raw_ostream</tt> is not a template and can
				1167	be forward declared as <tt>class raw_ostream</tt>. Public headers should
				1168	generally not include the <tt>raw_ostream</tt> header, but use forward
				1169	declarations and constant references to <tt>raw_ostream</tt> instances.</p>
				1170
				1171	</div>
				1172
				1173
				1174	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1175	<h4>
Chris Lattner	6883a88	2006-07-27 04:24:14 +0000	[diff] [blame]	1176	<a name="ll_avoidendl">Avoid <tt>std::endl</tt></a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1177	</h4>
Chris Lattner	13c4659	2002-01-20 19:01:26 +0000	[diff] [blame]	1178
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1179	<div class="doc_text">
				1180
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1181	<p>The <tt>std::endl</tt> modifier, when used with <tt>iostreams</tt> outputs a
				1182	newline to the output stream specified. In addition to doing this, however, it
				1183	also flushes the output stream. In other words, these are equivalent:</p>
Chris Lattner	13c4659	2002-01-20 19:01:26 +0000	[diff] [blame]	1184
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	1185	<div class="doc_code">
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	std::cout << std::endl;
				1188	std::cout << '\n' << std::flush;
Chris Lattner	13c4659	2002-01-20 19:01:26 +0000	[diff] [blame]	1189	</pre>
Misha Brukman	a8c760a	2004-07-28 22:31:54 +0000	[diff] [blame]	1190	</div>
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	<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]	1193	it's better to use a literal <tt>'\n'</tt>.</p>
Chris Lattner	13c4659	2002-01-20 19:01:26 +0000	[diff] [blame]	1194
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1195	</div>
Chris Lattner	13c4659	2002-01-20 19:01:26 +0000	[diff] [blame]	1196
Bill Wendling	7f564c0	2006-12-09 01:20:34 +0000	[diff] [blame]	1197
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1198	<!-- ======================================================================= -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1199	<h3>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1200	<a name="nano">Microscopic Details</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1201	</h3>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1202	<!-- ======================================================================= -->
				1203
				1204	<p>This section describes preferred low-level formatting guidelines along with
				1205	reasoning on why we prefer them.</p>
				1206
				1207	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1208	<h4>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1209	<a name="micro_spaceparen">Spaces Before Parentheses</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1210	</h4>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1211
				1212	<div class="doc_text">
				1213
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	1214	<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]	1215	statements, but not in normal function call expressions and function-like
				1216	macros. For example, this is good:</p>
				1217
				1218	<div class="doc_code">
				1219	<pre>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1220	<b>if (</b>x) ...
				1221	<b>for (</b>i = 0; i != 100; ++i) ...
				1222	<b>while (</b>llvm_rocks) ...
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	<b>somefunc(</b>42);
				1225	<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]	1226
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1227	a = <b>foo(</b>42, 92) + <b>bar(</b>x);
				1228	</pre>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1229	</div>
				1230
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1231	<p>and this is bad:</p>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1232
				1233	<div class="doc_code">
				1234	<pre>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1235	<b>if(</b>x) ...
				1236	<b>for(</b>i = 0; i != 100; ++i) ...
				1237	<b>while(</b>llvm_rocks) ...
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	<b>somefunc (</b>42);
				1240	<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]	1241
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1242	a = <b>foo (</b>42, 92) + <b>bar (</b>x);
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1243	</pre>
				1244	</div>
				1245
				1246	<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]	1247	control flow operators stand out more, and makes expressions flow better. The
				1248	function call operator binds very tightly as a postfix operator. Putting a
				1249	space after a function name (as in the last example) makes it appear that the
				1250	code might bind the arguments of the left-hand-side of a binary operator with
				1251	the argument list of a function and the name of the right side. More
				1252	specifically, it is easy to misread the "a" example as:</p>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1253
				1254	<div class="doc_code">
				1255	<pre>
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1256	a = foo <b>(</b>(42, 92) + bar<b>)</b> (x);
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1257	</pre>
				1258	</div>
				1259
Bill Wendling	b860203	2010-12-21 03:31:05 +0000	[diff] [blame]	1260	<p>when skimming through the code. By avoiding a space in a function, we avoid
				1261	this misinterpretation.</p>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1262
				1263	</div>
				1264
				1265	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1266	<h4>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1267	<a name="micro_preincrement">Prefer Preincrement</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1268	</h4>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1269
				1270	<div class="doc_text">
				1271
				1272	<p>Hard fast rule: Preincrement (<tt>++X</tt>) may be no slower than
				1273	postincrement (<tt>X++</tt>) and could very well be a lot faster than it. Use
				1274	preincrementation whenever possible.</p>
				1275
				1276	<p>The semantics of postincrement include making a copy of the value being
				1277	incremented, returning it, and then preincrementing the "work value". For
				1278	primitive types, this isn't a big deal... but for iterators, it can be a huge
				1279	issue (for example, some iterators contains stack and set objects in them...
				1280	copying an iterator could invoke the copy ctor's of these as well). In general,
				1281	get in the habit of always using preincrement, and you won't have a problem.</p>
				1282
				1283	</div>
				1284
				1285	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1286	<h4>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1287	<a name="micro_namespaceindent">Namespace Indentation</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1288	</h4>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1289
				1290	<div class="doc_text">
				1291
				1292	<p>
Chris Lattner	684cf81	2010-11-17 17:14:55 +0000	[diff] [blame]	1293	In general, we strive to reduce indentation wherever possible. This is useful
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1294	because we want code to <a href="#scf_codewidth">fit into 80 columns</a> without
				1295	wrapping horribly, but also because it makes it easier to understand the code.
				1296	Namespaces are a funny thing: they are often large, and we often desire to put
				1297	lots of stuff into them (so they can be large). Other times they are tiny,
				1298	because they just hold an enum or something similar. In order to balance this,
				1299	we use different approaches for small versus large namespaces.
				1300	</p>
				1301
				1302	<p>
				1303	If a namespace definition is small and <em>easily</em> fits on a screen (say,
				1304	less than 35 lines of code), then you should indent its body. Here's an
				1305	example:
				1306	</p>
				1307
				1308	<div class="doc_code">
				1309	<pre>
Chris Lattner	59fec6a	2009-07-22 16:54:14 +0000	[diff] [blame]	1310	namespace llvm {
				1311	namespace X86 {
				1312	/// RelocationType - An enum for the x86 relocation codes. Note that
				1313	/// the terminology here doesn't follow x86 convention - word means
				1314	/// 32-bit and dword means 64-bit.
				1315	enum RelocationType {
				1316	/// reloc_pcrel_word - PC relative relocation, add the relocated value to
				1317	/// the value already in memory, after we adjust it for where the PC is.
				1318	reloc_pcrel_word = 0,
				1319
				1320	/// reloc_picrel_word - PIC base relative relocation, add the relocated
				1321	/// value to the value already in memory, after we adjust it for where the
				1322	/// PIC base is.
				1323	reloc_picrel_word = 1,
				1324
				1325	/// reloc_absolute_word, reloc_absolute_dword - Absolute relocation, just
				1326	/// add the relocated value to the value already in memory.
				1327	reloc_absolute_word = 2,
				1328	reloc_absolute_dword = 3
				1329	};
				1330	}
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1331	}
				1332	</pre>
				1333	</div>
				1334
				1335	<p>Since the body is small, indenting adds value because it makes it very clear
				1336	where the namespace starts and ends, and it is easy to take the whole thing in
				1337	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]	1338	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]	1339	indent the code, and add a comment indicating what namespace is being closed.
				1340	For example:</p>
				1341
				1342	<div class="doc_code">
				1343	<pre>
				1344	namespace llvm {
				1345	namespace knowledge {
				1346
				1347	/// Grokable - This class represents things that Smith can have an intimate
				1348	/// understanding of and contains the data associated with it.
				1349	class Grokable {
				1350	...
				1351	public:
				1352	explicit Grokable() { ... }
				1353	virtual ~Grokable() = 0;
				1354
				1355	...
				1356
				1357	};
				1358
				1359	} // end namespace knowledge
				1360	} // end namespace llvm
				1361	</pre>
				1362	</div>
				1363
				1364	<p>Because the class is large, we don't expect that the reader can easily
				1365	understand the entire concept in a glance, and the end of the file (where the
				1366	namespaces end) may be a long ways away from the place they open. As such,
				1367	indenting the contents of the namespace doesn't add any value, and detracts from
				1368	the readability of the class. In these cases it is best to <em>not</em> indent
				1369	the contents of the namespace.</p>
				1370
				1371	</div>
				1372
				1373	<!-- _______________________________________________________________________ -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1374	<h4>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1375	<a name="micro_anonns">Anonymous Namespaces</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1376	</h4>
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1377
				1378	<div class="doc_text">
				1379
Chris Lattner	59fec6a	2009-07-22 16:54:14 +0000	[diff] [blame]	1380	<p>After talking about namespaces in general, you may be wondering about
				1381	anonymous namespaces in particular.
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1382	Anonymous namespaces are a great language feature that tells the C++ compiler
				1383	that the contents of the namespace are only visible within the current
				1384	translation unit, allowing more aggressive optimization and eliminating the
				1385	possibility of symbol name collisions. Anonymous namespaces are to C++ as
				1386	"static" is to C functions and global variables. While "static" is available
				1387	in C++, anonymous namespaces are more general: they can make entire classes
				1388	private to a file.</p>
				1389
				1390	<p>The problem with anonymous namespaces is that they naturally want to
				1391	encourage indentation of their body, and they reduce locality of reference: if
				1392	you see a random function definition in a C++ file, it is easy to see if it is
				1393	marked static, but seeing if it is in an anonymous namespace requires scanning
				1394	a big chunk of the file.</p>
				1395
				1396	<p>Because of this, we have a simple guideline: make anonymous namespaces as
				1397	small as possible, and only use them for class declarations. For example, this
				1398	is good:</p>
				1399
				1400	<div class="doc_code">
				1401	<pre>
				1402	<b>namespace {</b>
				1403	class StringSort {
				1404	...
				1405	public:
				1406	StringSort(...)
				1407	bool operator<(const char *RHS) const;
				1408	};
				1409	<b>} // end anonymous namespace</b>
				1410
				1411	static void Helper() {
				1412	...
				1413	}
				1414
				1415	bool StringSort::operator<(const char *RHS) const {
				1416	...
				1417	}
				1418
				1419	</pre>
				1420	</div>
				1421
				1422	<p>This is bad:</p>
				1423
				1424
				1425	<div class="doc_code">
				1426	<pre>
				1427	<b>namespace {</b>
				1428	class StringSort {
				1429	...
				1430	public:
				1431	StringSort(...)
				1432	bool operator<(const char *RHS) const;
				1433	};
				1434
				1435	void Helper() {
				1436	...
				1437	}
				1438
				1439	bool StringSort::operator<(const char *RHS) const {
				1440	...
				1441	}
				1442
				1443	<b>} // end anonymous namespace</b>
				1444
				1445	</pre>
				1446	</div>
				1447
				1448
				1449	<p>This is bad specifically because if you're looking at "Helper" in the middle
				1450	of a large C++ file, that you have no immediate way to tell if it is local to
				1451	the file. When it is marked static explicitly, this is immediately obvious.
				1452	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]	1453	namespace just because it was declared there.
Chris Lattner	d283cb1	2009-07-22 05:40:54 +0000	[diff] [blame]	1454	</p>
				1455
				1456	</div>
				1457
				1458
				1459
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1460	<!-- *********************************************************************** -->
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1461	<h2>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1462	<a name="seealso">See Also</a>
NAKAMURA Takumi	05d0265	2011-04-18 23:59:50 +0000	[diff] [blame]	1463	</h2>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1464	<!-- *********************************************************************** -->
				1465
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1466	<div class="doc_text">
				1467
				1468	<p>A lot of these comments and recommendations have been culled for other
				1469	sources. Two particularly important books for our work are:</p>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1470
				1471	<ol>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1472
Chris Lattner	788ee28	2007-11-09 21:49:08 +0000	[diff] [blame]	1473	<li><a href="http://www.amazon.com/Effective-Specific-Addison-Wesley-Professional-Computing/dp/0321334876">Effective
				1474	C++</a> by Scott Meyers. Also
Chris Lattner	999cf09	2004-05-23 21:05:07 +0000	[diff] [blame]	1475	interesting and useful are "More Effective C++" and "Effective STL" by the same
				1476	author.</li>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1477
Chris Lattner	788ee28	2007-11-09 21:49:08 +0000	[diff] [blame]	1478	<li>Large-Scale C++ Software Design by John Lakos</li>
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1479
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1480	</ol>
				1481
				1482	<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]	1483	something.</p>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1484
				1485	</div>
				1486
Chris Lattner	d80c43c	2001-07-09 03:27:08 +0000	[diff] [blame]	1487	<!-- *********************************************************************** -->
				1488
				1489	<hr>
Misha Brukman	6c16c4b	2004-05-12 18:37:22 +0000	[diff] [blame]	1490	<address>
				1491	<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
Misha Brukman	4440870	2008-12-11 17:34:48 +0000	[diff] [blame]	1492	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]	1493	<a href="http://validator.w3.org/check/referer"><img
Misha Brukman	4440870	2008-12-11 17:34:48 +0000	[diff] [blame]	1494	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]	1495
Misha Brukman	6c16c4b	2004-05-12 18:37:22 +0000	[diff] [blame]	1496	<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
NAKAMURA Takumi	b9a3363	2011-04-09 02:13:37 +0000	[diff] [blame]	1497	<a href="http://llvm.org/">LLVM Compiler Infrastructure</a><br>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1498	Last modified: $Date$
Misha Brukman	6c16c4b	2004-05-12 18:37:22 +0000	[diff] [blame]	1499	</address>
Misha Brukman	75f258e	2003-10-24 17:57:33 +0000	[diff] [blame]	1500
				1501	</body>
				1502	</html>