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

blob: 6e1c240a000ec812fff3b465e2f8b7876baf1810 [file] [log] [blame]

Dan Gohman	f17a25c	2007-07-18 16:29:46 +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	4dbc9d5	2008-12-10 23:07:02 +0000	[diff] [blame]	6	<title>LLVM Coding Standards</title>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	7	</head>
				8	<body>
				9
				10	<div class="doc_title">
Misha Brukman	4dbc9d5	2008-12-10 23:07:02 +0000	[diff] [blame]	11	LLVM Coding Standards
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	12	</div>
				13
				14	<ol>
				15	<li><a href="#introduction">Introduction</a></li>
				16	<li><a href="#mechanicalissues">Mechanical Source Issues</a>
				17	<ol>
				18	<li><a href="#sourceformating">Source Code Formatting</a>
				19	<ol>
				20	<li><a href="#scf_commenting">Commenting</a></li>
				21	<li><a href="#scf_commentformat">Comment Formatting</a></li>
				22	<li><a href="#scf_includes"><tt>#include</tt> Style</a></li>
				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>
				27	<li><a href="#compilerissues">Compiler Issues</a>
				28	<ol>
				29	<li><a href="#ci_warningerrors">Treat Compiler Warnings Like
				30	Errors</a></li>
				31	<li><a href="#ci_portable_code">Write Portable Code</a></li>
				32	<li><a href="#ci_class_struct">Use of class/struct Keywords</a></li>
				33	</ol></li>
				34	</ol></li>
				35	<li><a href="#styleissues">Style Issues</a>
				36	<ol>
				37	<li><a href="#macro">The High Level Issues</a>
				38	<ol>
				39	<li><a href="#hl_module">A Public Header File <b>is</b> a
				40	Module</a></li>
				41	<li><a href="#hl_dontinclude">#include as Little as Possible</a></li>
				42	<li><a href="#hl_privateheaders">Keep "internal" Headers
				43	Private</a></li>
Chris Lattner	eb1e8c3	2009-07-22 05:40:54 +0000	[diff] [blame]	44	<li><a href="#hl_earlyexit">Use Early Exits and 'continue' to Simplify
				45	Code</a></li>
				46	<li><a href="#hl_predicateloops">Turn Predicate Loops into Predicate
				47	Functions</a></li>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	48	</ol></li>
				49	<li><a href="#micro">The Low Level Issues</a>
				50	<ol>
				51	<li><a href="#ll_assert">Assert Liberally</a></li>
				52	<li><a href="#ll_ns_std">Do not use 'using namespace std'</a></li>
				53	<li><a href="#ll_virtual_anch">Provide a virtual method anchor for
				54	classes in headers</a></li>
Chris Lattner	01b8af3	2009-06-30 06:13:23 +0000	[diff] [blame]	55	<li><a href="#ll_end">Don't evaluate end() every time through a
				56	loop</a></li>
Chris Lattner	eb1e8c3	2009-07-22 05:40:54 +0000	[diff] [blame]	57	<li><a href="#ll_iostream"><tt>#include <iostream></tt> is
				58	<em>forbidden</em></a></li>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	59	<li><a href="#ll_avoidendl">Avoid <tt>std::endl</tt></a></li>
				60	</ol></li>
Chris Lattner	eb1e8c3	2009-07-22 05:40:54 +0000	[diff] [blame]	61
				62	<li><a href="#nano">Microscopic Details</a>
				63	<ol>
				64	<li><a href="#micro_spaceparen">Spaces Before Parentheses</a></li>
				65	<li><a href="#micro_preincrement">Prefer Preincrement</a></li>
				66	<li><a href="#micro_namespaceindent">Namespace Indentation</a></li>
				67	<li><a href="#micro_anonns">Anonymous Namespaces</a></li>
				68	</ol></li>
				69
				70
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	71	</ol></li>
				72	<li><a href="#seealso">See Also</a></li>
				73	</ol>
				74
				75	<div class="doc_author">
Chris Lattner	e7346a9	2009-07-22 05:43:01 +0000	[diff] [blame^]	76	<p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a></p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	77	</div>
				78
				79
				80	<!-- *********************************************************************** -->
				81	<div class="doc_section">
				82	<a name="introduction">Introduction</a>
				83	</div>
				84	<!-- *********************************************************************** -->
				85
				86	<div class="doc_text">
				87
				88	<p>This document attempts to describe a few coding standards that are being used
				89	in the LLVM source tree. Although no coding standards should be regarded as
				90	absolute requirements to be followed in all instances, coding standards can be
				91	useful.</p>
				92
				93	<p>This document intentionally does not prescribe fixed standards for religious
				94	issues such as brace placement and space usage. For issues like this, follow
				95	the golden rule:</p>
				96
				97	<blockquote>
				98
				99	<p><b><a name="goldenrule">If you are adding a significant body of source to a
				100	project, feel free to use whatever style you are most comfortable with. If you
				101	are extending, enhancing, or bug fixing already implemented code, use the style
				102	that is already being used so that the source is uniform and easy to
				103	follow.</a></b></p>
				104
				105	</blockquote>
				106
				107	<p>The ultimate goal of these guidelines is the increase readability and
				108	maintainability of our common source base. If you have suggestions for topics to
				109	be included, please mail them to <a
				110	href="mailto:sabre@nondot.org">Chris</a>.</p>
				111
				112	</div>
				113
				114	<!-- *********************************************************************** -->
				115	<div class="doc_section">
				116	<a name="mechanicalissues">Mechanical Source Issues</a>
				117	</div>
				118	<!-- *********************************************************************** -->
				119
				120	<!-- ======================================================================= -->
				121	<div class="doc_subsection">
				122	<a name="sourceformating">Source Code Formatting</a>
				123	</div>
				124
				125	<!-- _______________________________________________________________________ -->
				126	<div class="doc_subsubsection">
				127	<a name="scf_commenting">Commenting</a>
				128	</div>
				129
				130	<div class="doc_text">
				131
				132	<p>Comments are one critical part of readability and maintainability. Everyone
Chris Lattner	4838669	2009-07-12 00:10:24 +0000	[diff] [blame]	133	knows they should comment, so should you. When writing comments, write them as
				134	English prose, which means they should use proper capitalization, punctuation,
				135	etc. Although we all should probably
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	136	comment our code more than we do, there are a few very critical places that
				137	documentation is very useful:</p>
				138
				139	<b>File Headers</b>
				140
				141	<p>Every source file should have a header on it that describes the basic
				142	purpose of the file. If a file does not have a header, it should not be
				143	checked into Subversion. Most source trees will probably have a standard
				144	file header format. The standard format for the LLVM source tree looks like
				145	this:</p>
				146
				147	<div class="doc_code">
				148	<pre>
				149	//===-- llvm/Instruction.h - Instruction class definition -------- C++ --===//
Misha Brukman	0fd5f3e	2009-01-02 16:58:42 +0000	[diff] [blame]	150	//
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	151	// The LLVM Compiler Infrastructure
				152	//
Chris Lattner	fb5959f	2007-12-29 19:56:08 +0000	[diff] [blame]	153	// This file is distributed under the University of Illinois Open Source
				154	// License. See LICENSE.TXT for details.
Misha Brukman	0fd5f3e	2009-01-02 16:58:42 +0000	[diff] [blame]	155	//
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	156	//===----------------------------------------------------------------------===//
				157	//
				158	// This file contains the declaration of the Instruction class, which is the
				159	// base class for all of the VM instructions.
				160	//
				161	//===----------------------------------------------------------------------===//
				162	</pre>
				163	</div>
				164
Chris Lattner	fb5959f	2007-12-29 19:56:08 +0000	[diff] [blame]	165	<p>A few things to note about this particular format: The "<tt>-*- C++
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	166	-*-</tt>" string on the first line is there to tell Emacs that the source file
				167	is a C++ file, not a C file (Emacs assumes .h files are C files by default).
				168	Note that this tag is not necessary in .cpp files. The name of the file is also
				169	on the first line, along with a very short description of the purpose of the
				170	file. This is important when printing out code and flipping though lots of
				171	pages.</p>
				172
Chris Lattner	fb5959f	2007-12-29 19:56:08 +0000	[diff] [blame]	173	<p>The next section in the file is a concise note that defines the license
				174	that the file is released under. This makes it perfectly clear what terms the
				175	source code can be distributed under and should not be modified in any way.</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	176
				177	<p>The main body of the description does not have to be very long in most cases.
				178	Here it's only two lines. If an algorithm is being implemented or something
				179	tricky is going on, a reference to the paper where it is published should be
				180	included, as well as any notes or "gotchas" in the code to watch out for.</p>
				181
				182	<b>Class overviews</b>
				183
				184	<p>Classes are one fundamental part of a good object oriented design. As such,
				185	a class definition should have a comment block that explains what the class is
				186	used for... if it's not obvious. If it's so completely obvious your grandma
				187	could figure it out, it's probably safe to leave it out. Naming classes
				188	something sane goes a long ways towards avoiding writing documentation.</p>
				189
				190
				191	<b>Method information</b>
				192
				193	<p>Methods defined in a class (as well as any global functions) should also be
				194	documented properly. A quick note about what it does any a description of the
				195	borderline behaviour is all that is necessary here (unless something
				196	particularly tricky or insideous is going on). The hope is that people can
				197	figure out how to use your interfaces without reading the code itself... that is
				198	the goal metric.</p>
				199
				200	<p>Good things to talk about here are what happens when something unexpected
				201	happens: does the method return null? Abort? Format your hard disk?</p>
				202
				203	</div>
				204
				205	<!-- _______________________________________________________________________ -->
				206	<div class="doc_subsubsection">
				207	<a name="scf_commentformat">Comment Formatting</a>
				208	</div>
				209
				210	<div class="doc_text">
				211
				212	<p>In general, prefer C++ style (<tt>//</tt>) comments. They take less space,
				213	require less typing, don't have nesting problems, etc. There are a few cases
				214	when it is useful to use C style (<tt>/* */</tt>) comments however:</p>
				215
				216	<ol>
				217	<li>When writing a C code: Obviously if you are writing C code, use C style
				218	comments.</li>
				219	<li>When writing a header file that may be <tt>#include</tt>d by a C source
				220	file.</li>
				221	<li>When writing a source file that is used by a tool that only accepts C
				222	style comments.</li>
				223	</ol>
				224
				225	<p>To comment out a large block of code, use <tt>#if 0</tt> and <tt>#endif</tt>.
				226	These nest properly and are better behaved in general than C style comments.</p>
				227
				228	</div>
				229
				230	<!-- _______________________________________________________________________ -->
				231	<div class="doc_subsubsection">
				232	<a name="scf_includes"><tt>#include</tt> Style</a>
				233	</div>
				234
				235	<div class="doc_text">
				236
				237	<p>Immediately after the <a href="#scf_commenting">header file comment</a> (and
				238	include guards if working on a header file), the <a
				239	href="#hl_dontinclude">minimal</a> list of <tt>#include</tt>s required by the
				240	file should be listed. We prefer these <tt>#include</tt>s to be listed in this
				241	order:</p>
				242
				243	<ol>
				244	<li><a href="#mmheader">Main Module header</a></li>
				245	<li><a href="#hl_privateheaders">Local/Private Headers</a></li>
				246	<li><tt>llvm/*</tt></li>
				247	<li><tt>llvm/Analysis/*</tt></li>
				248	<li><tt>llvm/Assembly/*</tt></li>
				249	<li><tt>llvm/Bytecode/*</tt></li>
				250	<li><tt>llvm/CodeGen/*</tt></li>
				251	<li>...</li>
				252	<li><tt>Support/*</tt></li>
				253	<li><tt>Config/*</tt></li>
				254	<li>System <tt>#includes</tt></li>
				255	</ol>
				256
Nick Lewycky	61819f7	2008-11-29 20:13:25 +0000	[diff] [blame]	257	<p>... and each category should be sorted by name.</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	258
				259	<p><a name="mmheader">The "Main Module Header"</a> file applies to .cpp file
				260	which implement an interface defined by a .h file. This <tt>#include</tt>
				261	should always be included <b>first</b> regardless of where it lives on the file
				262	system. By including a header file first in the .cpp files that implement the
				263	interfaces, we ensure that the header does not have any hidden dependencies
				264	which are not explicitly #included in the header, but should be. It is also a
				265	form of documentation in the .cpp file to indicate where the interfaces it
				266	implements are defined.</p>
				267
				268	</div>
				269
				270	<!-- _______________________________________________________________________ -->
				271	<div class="doc_subsubsection">
				272	<a name="scf_codewidth">Source Code Width</a>
				273	</div>
				274
				275	<div class="doc_text">
				276
				277	<p>Write your code to fit within 80 columns of text. This helps those of us who
				278	like to print out code and look at your code in an xterm without resizing
				279	it.</p>
				280
Chris Lattner	b5daf70	2008-07-08 05:12:37 +0000	[diff] [blame]	281	<p>The longer answer is that there must be some limit to the width of the code
				282	in order to reasonably allow developers to have multiple files side-by-side in
				283	windows on a modest display. If you are going to pick a width limit, it is
				284	somewhat arbitrary but you might as well pick something standard. Going with
				285	90 columns (for example) instead of 80 columns wouldn't add any significant
				286	value and would be detrimental to printing out code. Also many other projects
				287	have standardized on 80 columns, so some people have already configured their
				288	editors for it (vs something else, like 90 columns).</p>
				289
				290	<p>This is one of many contentious issues in coding standards, but is not up
				291	for debate.</p>
				292
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	293	</div>
				294
				295	<!-- _______________________________________________________________________ -->
				296	<div class="doc_subsubsection">
				297	<a name="scf_spacestabs">Use Spaces Instead of Tabs</a>
				298	</div>
				299
				300	<div class="doc_text">
				301
				302	<p>In all cases, prefer spaces to tabs in source files. People have different
				303	prefered indentation levels, and different styles of indentation that they
				304	like... this is fine. What isn't is that different editors/viewers expand tabs
				305	out to different tab stops. This can cause your code to look completely
				306	unreadable, and it is not worth dealing with.</p>
				307
				308	<p>As always, follow the <a href="#goldenrule">Golden Rule</a> above: follow the
				309	style of existing code if your are modifying and extending it. If you like four
				310	spaces of indentation, <b>DO NOT</b> do that in the middle of a chunk of code
				311	with two spaces of indentation. Also, do not reindent a whole source file: it
				312	makes for incredible diffs that are absolutely worthless.</p>
				313
				314	</div>
				315
				316	<!-- _______________________________________________________________________ -->
				317	<div class="doc_subsubsection">
				318	<a name="scf_indentation">Indent Code Consistently</a>
				319	</div>
				320
				321	<div class="doc_text">
				322
				323	<p>Okay, your first year of programming you were told that indentation is
				324	important. If you didn't believe and internalize this then, now is the time.
				325	Just do it.</p>
				326
				327	</div>
				328
				329
				330	<!-- ======================================================================= -->
				331	<div class="doc_subsection">
				332	<a name="compilerissues">Compiler Issues</a>
				333	</div>
				334
				335
				336	<!-- _______________________________________________________________________ -->
				337	<div class="doc_subsubsection">
				338	<a name="ci_warningerrors">Treat Compiler Warnings Like Errors</a>
				339	</div>
				340
				341	<div class="doc_text">
				342
				343	<p>If your code has compiler warnings in it, something is wrong: you aren't
				344	casting values correctly, your have "questionable" constructs in your code, or
				345	you are doing something legitimately wrong. Compiler warnings can cover up
				346	legitimate errors in output and make dealing with a translation unit
				347	difficult.</p>
				348
				349	<p>It is not possible to prevent all warnings from all compilers, nor is it
				350	desirable. Instead, pick a standard compiler (like <tt>gcc</tt>) that provides
				351	a good thorough set of warnings, and stick to them. At least in the case of
				352	<tt>gcc</tt>, it is possible to work around any spurious errors by changing the
				353	syntax of the code slightly. For example, an warning that annoys me occurs when
				354	I write code like this:</p>
				355
				356	<div class="doc_code">
				357	<pre>
				358	if (V = getValue()) {
				359	...
				360	}
				361	</pre>
				362	</div>
				363
				364	<p><tt>gcc</tt> will warn me that I probably want to use the <tt>==</tt>
				365	operator, and that I probably mistyped it. In most cases, I haven't, and I
				366	really don't want the spurious errors. To fix this particular problem, I
				367	rewrite the code like this:</p>
				368
				369	<div class="doc_code">
				370	<pre>
				371	if ((V = getValue())) {
				372	...
				373	}
				374	</pre>
				375	</div>
				376
				377	<p>...which shuts <tt>gcc</tt> up. Any <tt>gcc</tt> warning that annoys you can
				378	be fixed by massaging the code appropriately.</p>
				379
				380	<p>These are the <tt>gcc</tt> warnings that I prefer to enable: <tt>-Wall
				381	-Winline -W -Wwrite-strings -Wno-unused</tt></p>
				382
				383	</div>
				384
				385	<!-- _______________________________________________________________________ -->
				386	<div class="doc_subsubsection">
				387	<a name="ci_portable_code">Write Portable Code</a>
				388	</div>
				389
				390	<div class="doc_text">
				391
				392	<p>In almost all cases, it is possible and within reason to write completely
				393	portable code. If there are cases where it isn't possible to write portable
				394	code, isolate it behind a well defined (and well documented) interface.</p>
				395
				396	<p>In practice, this means that you shouldn't assume much about the host
				397	compiler, including its support for "high tech" features like partial
Chris Lattner	afec025	2009-03-23 04:52:53 +0000	[diff] [blame]	398	specialization of templates. If these features are used, they should only be
				399	an implementation detail of a library which has a simple exposed API.</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	400
				401	</div>
				402
				403	<!-- _______________________________________________________________________ -->
				404	<div class="doc_subsubsection">
				405	<a name="ci_class_struct">Use of <tt>class</tt> and <tt>struct</tt> Keywords</a>
				406	</div>
				407	<div class="doc_text">
				408
				409	<p>In C++, the <tt>class</tt> and <tt>struct</tt> keywords can be used almost
				410	interchangeably. The only difference is when they are used to declare a class:
				411	<tt>class</tt> makes all members private by default while <tt>struct</tt> makes
				412	all members public by default.</p>
				413
				414	<p>Unfortunately, not all compilers follow the rules and some will generate
				415	different symbols based on whether <tt>class</tt> or <tt>struct</tt> was used to
				416	declare the symbol. This can lead to problems at link time.</p>
				417
				418	<p>So, the rule for LLVM is to always use the <tt>class</tt> keyword, unless
				419	<b>all</b> members are public, in which case <tt>struct</tt> is allowed.</p>
				420
				421	</div>
				422
				423	<!-- *********************************************************************** -->
				424	<div class="doc_section">
				425	<a name="styleissues">Style Issues</a>
				426	</div>
				427	<!-- *********************************************************************** -->
				428
				429
				430	<!-- ======================================================================= -->
				431	<div class="doc_subsection">
				432	<a name="macro">The High Level Issues</a>
				433	</div>
Chris Lattner	eb1e8c3	2009-07-22 05:40:54 +0000	[diff] [blame]	434	<!-- ======================================================================= -->
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	435
				436
				437	<!-- _______________________________________________________________________ -->
				438	<div class="doc_subsubsection">
				439	<a name="hl_module">A Public Header File <b>is</b> a Module</a>
				440	</div>
				441
				442	<div class="doc_text">
				443
				444	<p>C++ doesn't do too well in the modularity department. There is no real
				445	encapsulation or data hiding (unless you use expensive protocol classes), but it
				446	is what we have to work with. When you write a public header file (in the LLVM
				447	source tree, they live in the top level "include" directory), you are defining a
				448	module of functionality.</p>
				449
				450	<p>Ideally, modules should be completely independent of each other, and their
				451	header files should only include the absolute minimum number of headers
				452	possible. A module is not just a class, a function, or a namespace: <a
				453	href="http://www.cuj.com/articles/2000/0002/0002c/0002c.htm">it's a collection
				454	of these</a> that defines an interface. This interface may be several
				455	functions, classes or data structures, but the important issue is how they work
				456	together.</p>
				457
				458	<p>In general, a module should be implemented with one or more <tt>.cpp</tt>
				459	files. Each of these <tt>.cpp</tt> files should include the header that defines
				460	their interface first. This ensure that all of the dependences of the module
				461	header have been properly added to the module header itself, and are not
				462	implicit. System headers should be included after user headers for a
				463	translation unit.</p>
				464
				465	</div>
				466
				467	<!-- _______________________________________________________________________ -->
				468	<div class="doc_subsubsection">
				469	<a name="hl_dontinclude"><tt>#include</tt> as Little as Possible</a>
				470	</div>
				471
				472	<div class="doc_text">
				473
				474	<p><tt>#include</tt> hurts compile time performance. Don't do it unless you
				475	have to, especially in header files.</p>
				476
				477	<p>But wait, sometimes you need to have the definition of a class to use it, or
				478	to inherit from it. In these cases go ahead and <tt>#include</tt> that header
				479	file. Be aware however that there are many cases where you don't need to have
				480	the full definition of a class. If you are using a pointer or reference to a
				481	class, you don't need the header file. If you are simply returning a class
				482	instance from a prototyped function or method, you don't need it. In fact, for
				483	most cases, you simply don't need the definition of a class... and not
				484	<tt>#include</tt>'ing speeds up compilation.</p>
				485
				486	<p>It is easy to try to go too overboard on this recommendation, however. You
				487	<b>must</b> include all of the header files that you are using -- you can
				488	include them either directly
				489	or indirectly (through another header file). To make sure that you don't
				490	accidently forget to include a header file in your module header, make sure to
				491	include your module header <b>first</b> in the implementation file (as mentioned
				492	above). This way there won't be any hidden dependencies that you'll find out
				493	about later...</p>
				494
				495	</div>
				496
				497	<!-- _______________________________________________________________________ -->
				498	<div class="doc_subsubsection">
				499	<a name="hl_privateheaders">Keep "internal" Headers Private</a>
				500	</div>
				501
				502	<div class="doc_text">
				503
				504	<p>Many modules have a complex implementation that causes them to use more than
				505	one implementation (<tt>.cpp</tt>) file. It is often tempting to put the
				506	internal communication interface (helper classes, extra functions, etc) in the
				507	public module header file. Don't do this.</p>
				508
				509	<p>If you really need to do something like this, put a private header file in
				510	the same directory as the source files, and include it locally. This ensures
				511	that your private interface remains private and undisturbed by outsiders.</p>
				512
				513	<p>Note however, that it's okay to put extra implementation methods a public
				514	class itself... just make them private (or protected), and all is well.</p>
				515
				516	</div>
				517
				518	<!-- _______________________________________________________________________ -->
				519	<div class="doc_subsubsection">
Chris Lattner	eb1e8c3	2009-07-22 05:40:54 +0000	[diff] [blame]	520	<a name="hl_earlyexit">Use Early Exits and 'continue' to Simplify Code</a>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	521	</div>
				522
				523	<div class="doc_text">
				524
Chris Lattner	eb1e8c3	2009-07-22 05:40:54 +0000	[diff] [blame]	525	<p>When reading code, keep in mind how much state and how many previous
				526	decisions have to be remembered by the reader to understand a block of code.
				527	Aim to reduce indentation where possible when it doesn't make it more difficult
				528	to understand the code. One great way to do this is by making use of early
				529	exits and the 'continue' keyword in long loops. As an example of using an early
				530	exit from a function, consider this "bad" code:</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	531
Chris Lattner	eb1e8c3	2009-07-22 05:40:54 +0000	[diff] [blame]	532	<div class="doc_code">
				533	<pre>
				534	Value DoSomething(Instruction I) {
				535	if (!isa<TerminatorInst>(I) &&
				536	I->hasOneUse() && SomeOtherThing(I)) {
				537	... some long code ....
				538	}
				539
				540	return 0;
				541	}
				542	</pre>
				543	</div>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	544
Chris Lattner	eb1e8c3	2009-07-22 05:40:54 +0000	[diff] [blame]	545	<p>This code has several problems if the body of the 'if' is large. When you're
				546	looking at the top of the function, it isn't immediately clear that this
				547	<em>only</em> does interesting things with non-terminator instructions, and only
				548	applies to things with the other predicates. Second, it is relatively difficult
				549	to describe (in comments) why these predicates are important because the if
				550	statement makes it difficult to lay out the comments. Third, when you're deep
				551	within the body of the code, it is indented an extra level. Finally, when
				552	reading the top of the function, it isn't clear what the result is if the
				553	predicate isn't true, you have to read to the end of the function to know that
				554	it returns null.</p>
Matthijs Kooijman	c4c0af2	2008-07-30 12:14:10 +0000	[diff] [blame]	555
Chris Lattner	eb1e8c3	2009-07-22 05:40:54 +0000	[diff] [blame]	556	<p>It is much preferred to format the code like this:</p>
				557
				558	<div class="doc_code">
				559	<pre>
				560	Value DoSomething(Instruction I) {
				561	// Terminators never need 'something' done to them because, ...
				562	if (isa<TerminatorInst>(I))
				563	return 0;
				564
				565	// We conservatively avoid transforming instructions with multiple uses
				566	// because goats like cheese.
				567	if (!I->hasOneUse())
				568	return 0;
				569
				570	// This is really just here for example.
				571	if (!SomeOtherThing(I))
				572	return 0;
				573
				574	... some long code ....
				575	}
				576	</pre>
				577	</div>
				578
				579	<p>This fixes these problems. A similar problem frequently happens in for
				580	loops. A silly example is something like this:</p>
				581
				582	<div class="doc_code">
				583	<pre>
				584	for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II != E; ++II) {
				585	if (BinaryOperator *BO = dyn_cast<BinaryOperator>(II)) {
				586	Value *LHS = BO->getOperand(0);
				587	Value *RHS = BO->getOperand(1);
				588	if (LHS != RHS) {
				589	...
				590	}
				591	}
				592	}
				593	</pre>
				594	</div>
				595
				596	<p>When you have very very small loops, this sort of structure is fine, but if
				597	it exceeds more than 10-15 lines, it becomes difficult for people to read and
				598	understand at a glance.
				599	The problem with this sort of code is that it gets very nested very quickly,
				600	meaning that the reader of the code has to keep a lot of context in their brain
				601	to remember what is going immediately on in the loop, because they don't know
				602	if/when the if conditions will have elses etc. It is strongly preferred to
				603	structure the loop like this:</p>
				604
				605	<div class="doc_code">
				606	<pre>
				607	for (BasicBlock::iterator II = BB->begin(), E = BB->end(); II != E; ++II) {
				608	BinaryOperator *BO = dyn_cast<BinaryOperator>(II);
				609	if (!BO) continue;
				610
				611	Value *LHS = BO->getOperand(0);
				612	Value *RHS = BO->getOperand(1);
				613	if (LHS == RHS) continue;
				614	}
				615	</pre>
				616	</div>
				617
				618	<p>This has all the benefits of using early exits from functions: it reduces
				619	nesting of the loop, it makes it easier to describe why the conditions are true,
				620	and it makes it obvious to the reader that there is no "else" coming up that
				621	they have to push context into their brain for. If a loop is large, this can
				622	be a big understandability win.</p>
				623
				624	</div>
				625
				626
				627	<!-- _______________________________________________________________________ -->
				628	<div class="doc_subsubsection">
				629	<a name="hl_predicateloops">Turn Predicate Loops into Predicate Functions</a>
				630	</div>
				631
				632	<div class="doc_text">
				633
				634	<p>It is very common to write inline functions that just compute a boolean
				635	value. There are a number of ways that people commonly write these, but an
				636	example of this sort of thing is:</p>
				637
				638	<div class="doc_code">
				639	<pre>
				640	<b>bool FoundFoo = false;</b>
				641	for (unsigned i = 0, e = BarList.size(); i != e; ++i)
				642	if (BarList[i]->isFoo()) {
				643	<b>FoundFoo = true;</b>
				644	break;
				645	}
				646
				647	<b>if (FoundFoo) {</b>
				648	...
				649	}
				650	</pre>
				651	</div>
				652
				653	<p>This sort of code is awkward to write, and is almost always a bad sign.
				654	Instead of this sort of loop, we strongly prefer to use a predicate function
				655	(which may be <a href="#micro_anonns">static</a>) that uses
				656	<a href="#hl_earlyexit">early exits</a> to compute the predicate. Code like
				657	this would be preferred:
				658	</p>
				659
				660
				661	<div class="doc_code">
				662	<pre>
				663	/// ListContainsFoo - Return true if the specified list has an element that is
				664	/// a foo.
				665	static bool ListContainsFoo(const std::vector<Bar*> &List) {
				666	for (unsigned i = 0, e = List.size(); i != e; ++i)
				667	if (List[i]->isFoo())
				668	return true;
				669	return false;
				670	}
				671	...
				672
				673	<b>if (ListContainsFoo(BarList)) {</b>
				674	...
				675	}
				676	</pre>
				677	</div>
				678
				679	<p>There are many reasons for doing this: it reduces indentation and factors out
				680	code which can often be shared by other code that checks for the same predicate.
				681	More importantly, it <em>forces you to pick a name</em> for the function, and
				682	forces you to write a comment for it. In this silly example, this doesn't add
				683	much value. However, if the condition is complex, this can make it a lot easier
				684	for the reader to understand the code that queries for this predicate. Instead
				685	of being faced with the in-line details of we check to see if the BarList
				686	contains a foo, we can trust the function name and continue reading with better
				687	locality.</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	688
				689	</div>
				690
				691
				692	<!-- ======================================================================= -->
				693	<div class="doc_subsection">
				694	<a name="micro">The Low Level Issues</a>
				695	</div>
Chris Lattner	eb1e8c3	2009-07-22 05:40:54 +0000	[diff] [blame]	696	<!-- ======================================================================= -->
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	697
				698
				699	<!-- _______________________________________________________________________ -->
				700	<div class="doc_subsubsection">
				701	<a name="ll_assert">Assert Liberally</a>
				702	</div>
				703
				704	<div class="doc_text">
				705
				706	<p>Use the "<tt>assert</tt>" function to its fullest. Check all of your
				707	preconditions and assumptions, you never know when a bug (not neccesarily even
				708	yours) might be caught early by an assertion, which reduces debugging time
				709	dramatically. The "<tt><cassert></tt>" header file is probably already
				710	included by the header files you are using, so it doesn't cost anything to use
				711	it.</p>
				712
				713	<p>To further assist with debugging, make sure to put some kind of error message
				714	in the assertion statement (which is printed if the assertion is tripped). This
				715	helps the poor debugging make sense of why an assertion is being made and
				716	enforced, and hopefully what to do about it. Here is one complete example:</p>
				717
				718	<div class="doc_code">
				719	<pre>
				720	inline Value *getOperand(unsigned i) {
				721	assert(i < Operands.size() && "getOperand() out of range!");
				722	return Operands[i];
				723	}
				724	</pre>
				725	</div>
				726
				727	<p>Here are some examples:</p>
				728
				729	<div class="doc_code">
				730	<pre>
				731	assert(Ty->isPointerType() && "Can't allocate a non pointer type!");
				732
				733	assert((Opcode == Shl \|\| Opcode == Shr) && "ShiftInst Opcode invalid!");
				734
				735	assert(idx < getNumSuccessors() && "Successor # out of range!");
				736
				737	assert(V1.getType() == V2.getType() && "Constant types must be identical!");
				738
				739	assert(isa<PHINode>(Succ->front()) && "Only works on PHId BBs!");
				740	</pre>
				741	</div>
				742
				743	<p>You get the idea...</p>
				744
Nick Lewycky	009216a	2008-05-31 23:54:55 +0000	[diff] [blame]	745	<p>Please be aware when adding assert statements that not all compilers are aware of
				746	the semantics of the assert. In some places, asserts are used to indicate a piece of
				747	code that should not be reached. These are typically of the form:</p>
				748
				749	<div class="doc_code">
				750	<pre>
Dan Gohman	4dfac70	2008-11-24 17:18:39 +0000	[diff] [blame]	751	assert(0 && "Some helpful error message");
Nick Lewycky	009216a	2008-05-31 23:54:55 +0000	[diff] [blame]	752	</pre>
				753	</div>
				754
				755	<p>When used in a function that returns a value, they should be followed with a return
				756	statement and a comment indicating that this line is never reached. This will prevent
				757	a compiler which is unable to deduce that the assert statement never returns from
				758	generating a warning.</p>
				759
				760	<div class="doc_code">
				761	<pre>
Dan Gohman	4dfac70	2008-11-24 17:18:39 +0000	[diff] [blame]	762	assert(0 && "Some helpful error message");
Nick Lewycky	009216a	2008-05-31 23:54:55 +0000	[diff] [blame]	763	// Not reached
				764	return 0;
				765	</pre>
				766	</div>
				767
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	768	</div>
				769
				770	<!-- _______________________________________________________________________ -->
				771	<div class="doc_subsubsection">
				772	<a name="ll_ns_std">Do not use '<tt>using namespace std</tt>'</a>
				773	</div>
				774
				775	<div class="doc_text">
				776	<p>In LLVM, we prefer to explicitly prefix all identifiers from the standard
				777	namespace with an "<tt>std::</tt>" prefix, rather than rely on
				778	"<tt>using namespace std;</tt>".</p>
				779
				780	<p> In header files, adding a '<tt>using namespace XXX</tt>' directive pollutes
Misha Brukman	bcc5373	2008-12-11 19:37:04 +0000	[diff] [blame]	781	the namespace of any source file that <tt>#include</tt>s the header. This is
				782	clearly a bad thing.</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	783
				784	<p>In implementation files (e.g. .cpp files), the rule is more of a stylistic
				785	rule, but is still important. Basically, using explicit namespace prefixes
				786	makes the code <b>clearer</b>, because it is immediately obvious what facilities
				787	are being used and where they are coming from, and <b>more portable</b>, because
				788	namespace clashes cannot occur between LLVM code and other namespaces. The
				789	portability rule is important because different standard library implementations
				790	expose different symbols (potentially ones they shouldn't), and future revisions
				791	to the C++ standard will add more symbols to the <tt>std</tt> namespace. As
				792	such, we never use '<tt>using namespace std;</tt>' in LLVM.</p>
				793
				794	<p>The exception to the general rule (i.e. it's not an exception for
				795	the <tt>std</tt> namespace) is for implementation files. For example, all of
				796	the code in the LLVM project implements code that lives in the 'llvm' namespace.
				797	As such, it is ok, and actually clearer, for the .cpp files to have a '<tt>using
				798	namespace llvm</tt>' directive at their top, after the <tt>#include</tt>s. The
				799	general form of this rule is that any .cpp file that implements code in any
				800	namespace may use that namespace (and its parents'), but should not use any
				801	others.</p>
				802
				803	</div>
				804
				805	<!-- _______________________________________________________________________ -->
				806	<div class="doc_subsubsection">
				807	<a name="ll_virtual_anch">Provide a virtual method anchor for classes
				808	in headers</a>
				809	</div>
				810
				811	<div class="doc_text">
				812
				813	<p>If a class is defined in a header file and has a v-table (either it has
				814	virtual methods or it derives from classes with virtual methods), it must
				815	always have at least one out-of-line virtual method in the class. Without
Misha Brukman	bcc5373	2008-12-11 19:37:04 +0000	[diff] [blame]	816	this, the compiler will copy the vtable and RTTI into every <tt>.o</tt> file
				817	that <tt>#include</tt>s the header, bloating <tt>.o</tt> file sizes and
				818	increasing link times.</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	819
				820	</div>
				821
Chris Lattner	01b8af3	2009-06-30 06:13:23 +0000	[diff] [blame]	822	<!-- _______________________________________________________________________ -->
				823	<div class="doc_subsubsection">
				824	<a name="ll_end">Don't evaluate end() every time through a loop</a>
				825	</div>
				826
				827	<div class="doc_text">
				828
				829	<p>Because C++ doesn't have a standard "foreach" loop (though it can be emulated
				830	with macros and may be coming in C++'0x) we end up writing a lot of loops that
				831	manually iterate from begin to end on a variety of containers or through other
				832	data structures. One common mistake is to write a loop in this style:</p>
				833
				834	<div class="doc_code">
				835	<pre>
				836	BasicBlock *BB = ...
				837	for (BasicBlock::iterator I = BB->begin(); I != <b>BB->end()</b>; ++I)
				838	... use I ...
				839	</pre>
				840	</div>
				841
				842	<p>The problem with this construct is that it evaluates "<tt>BB->end()</tt>"
				843	every time through the loop. Instead of writing the loop like this, we strongly
				844	prefer loops to be written so that they evaluate it once before the loop starts.
				845	A convenient way to do this is like so:</p>
				846
				847	<div class="doc_code">
				848	<pre>
				849	BasicBlock *BB = ...
				850	for (BasicBlock::iterator I = BB->begin(), E = <b>BB->end()</b>; I != E; ++I)
				851	... use I ...
				852	</pre>
				853	</div>
				854
				855	<p>The observant may quickly point out that these two loops may have different
				856	semantics: if the container (a basic block in this case) is being mutated, then
				857	"<tt>BB->end()</tt>" may change its value every time through the loop and the
				858	second loop may not in fact be correct. If you actually do depend on this
Chris Lattner	dc43b34	2009-06-30 06:20:03 +0000	[diff] [blame]	859	behavior, please write the loop in the first form and add a comment indicating
Chris Lattner	01b8af3	2009-06-30 06:13:23 +0000	[diff] [blame]	860	that you did it intentionally.</p>
				861
				862	<p>Why do we prefer the second form (when correct)? Writing the loop in the
				863	first form has two problems: First it may be less efficient than evaluating it
				864	at the start of the loop. In this case, the cost is probably minor: a few extra
				865	loads every time through the loop. However, if the base expression is more
				866	complex, then the cost can rise quickly. I've seen loops where the end
				867	expression was actually something like: "<tt>SomeMap[x]->end()</tt>" and map
Chris Lattner	088affa	2009-06-30 06:27:54 +0000	[diff] [blame]	868	lookups really aren't cheap. By writing it in the second form consistently, you
Chris Lattner	01b8af3	2009-06-30 06:13:23 +0000	[diff] [blame]	869	eliminate the issue entirely and don't even have to think about it.</p>
				870
Chris Lattner	dc43b34	2009-06-30 06:20:03 +0000	[diff] [blame]	871	<p>The second (even bigger) issue is that writing the loop in the first form
Chris Lattner	01b8af3	2009-06-30 06:13:23 +0000	[diff] [blame]	872	hints to the reader that the loop is mutating the container (a fact that a
				873	comment would handily confirm!). If you write the loop in the second form, it
				874	is immediately obvious without even looking at the body of the loop that the
				875	container isn't being modified, which makes it easier to read the code and
				876	understand what it does.</p>
				877
				878	<p>While the second form of the loop is a few extra keystrokes, we do strongly
				879	prefer it.</p>
				880
				881	</div>
				882
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	883	<!-- _______________________________________________________________________ -->
				884	<div class="doc_subsubsection">
Chris Lattner	eb1e8c3	2009-07-22 05:40:54 +0000	[diff] [blame]	885	<a name="ll_iostream"><tt>#include <iostream></tt> is forbidden</a>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	886	</div>
				887
				888	<div class="doc_text">
				889
Chris Lattner	eb1e8c3	2009-07-22 05:40:54 +0000	[diff] [blame]	890	<p>The use of <tt>#include <iostream></tt> in library files is
				891	hereby <b><em>forbidden</em></b>. The primary reason for doing this is to
				892	support clients using LLVM libraries as part of larger systems. In particular,
				893	we statically link LLVM into some dynamic libraries. Even if LLVM isn't used,
				894	the static c'tors are run whenever an application start up that uses the dynamic
				895	library. There are two problems with this:</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	896
Chris Lattner	eb1e8c3	2009-07-22 05:40:54 +0000	[diff] [blame]	897	<ol>
				898	<li>The time to run the static c'tors impacts startup time of
				899	applications—a critical time for GUI apps.</li>
				900	<li>The static c'tors cause the app to pull many extra pages of memory off the
				901	disk: both the code for the static c'tors in each <tt>.o</tt> file and the
				902	small amount of data that gets touched. In addition, touched/dirty pages
				903	put more pressure on the VM system on low-memory machines.</li>
				904	</ol>
				905
				906	<p>Note that using the other stream headers (<tt><sstream></tt> for
				907	example) is allowed normally, it is just <tt><iostream></tt> that is
				908	causing problems.</p>
				909
				910	<p>The preferred replacement for stream functionality is the
				911	<tt>llvm::raw_ostream</tt> class (for writing to output streams of various
				912	sorts) and the <tt>llvm::MemoryBuffer</tt> API (for reading in files).</p>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	913
				914	</div>
				915
Chris Lattner	eb1e8c3	2009-07-22 05:40:54 +0000	[diff] [blame]	916
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	917	<!-- _______________________________________________________________________ -->
				918	<div class="doc_subsubsection">
				919	<a name="ll_avoidendl">Avoid <tt>std::endl</tt></a>
				920	</div>
				921
				922	<div class="doc_text">
				923
				924	<p>The <tt>std::endl</tt> modifier, when used with iostreams outputs a newline
				925	to the output stream specified. In addition to doing this, however, it also
				926	flushes the output stream. In other words, these are equivalent:</p>
				927
				928	<div class="doc_code">
				929	<pre>
				930	std::cout << std::endl;
				931	std::cout << '\n' << std::flush;
				932	</pre>
				933	</div>
				934
				935	<p>Most of the time, you probably have no reason to flush the output stream, so
				936	it's better to use a literal <tt>'\n'</tt>.</p>
				937
				938	</div>
				939
				940
Chris Lattner	eb1e8c3	2009-07-22 05:40:54 +0000	[diff] [blame]	941	<!-- ======================================================================= -->
				942	<div class="doc_subsection">
				943	<a name="nano">Microscopic Details</a>
				944	</div>
				945	<!-- ======================================================================= -->
				946
				947	<p>This section describes preferred low-level formatting guidelines along with
				948	reasoning on why we prefer them.</p>
				949
				950	<!-- _______________________________________________________________________ -->
				951	<div class="doc_subsubsection">
				952	<a name="micro_spaceparen">Spaces Before Parentheses</a>
				953	</div>
				954
				955	<div class="doc_text">
				956
				957	<p>We prefer to put a space before a parentheses only in control flow
				958	statements, but not in normal function call expressions and function-like
				959	macros. For example, this is good:</p>
				960
				961	<div class="doc_code">
				962	<pre>
				963	<b>if (</b>x) ...
				964	<b>for (</b>i = 0; i != 100; ++i) ...
				965	<b>while (</b>llvm_rocks) ...
				966
				967	<b>somefunc(</b>42);
				968	<b><a href="#ll_assert">assert</a>(</b>3 != 4 && "laws of math are failing me");
				969
				970	a = <b>foo(</b>42, 92) + <b>bar(</b>x);
				971	</pre>
				972	</div>
				973
				974	<p>... and this is bad:</p>
				975
				976	<div class="doc_code">
				977	<pre>
				978	<b>if(</b>x) ...
				979	<b>for(</b>i = 0; i != 100; ++i) ...
				980	<b>while(</b>llvm_rocks) ...
				981
				982	<b>somefunc (</b>42);
				983	<b><a href="#ll_assert">assert</a> (</b>3 != 4 && "laws of math are failing me");
				984
				985	a = <b>foo (</b>42, 92) + <b>bar (</b>x);
				986	</pre>
				987	</div>
				988
				989	<p>The reason for doing this is not completely arbitrary. This style makes
				990	control flow operators stand out more, and makes expressions flow better. The
				991	function call operator binds very tightly as a postfix operator. Putting
				992	a space after a function name (as in the last example) makes it appear that
				993	the code might bind the arguments of the left-hand-side of a binary operator
				994	with the argument list of a function and the name of the right side. More
				995	specifically, it is easy to misread the "a" example as:</p>
				996
				997	<div class="doc_code">
				998	<pre>
				999	a = foo <b>(</b>(42, 92) + bar<b>)</b> (x);
				1000	</pre>
				1001	</div>
				1002
				1003	<p>... when skimming through the code. By avoiding a space in a function, we
				1004	avoid this misinterpretation.</p>
				1005
				1006	</div>
				1007
				1008	<!-- _______________________________________________________________________ -->
				1009	<div class="doc_subsubsection">
				1010	<a name="micro_preincrement">Prefer Preincrement</a>
				1011	</div>
				1012
				1013	<div class="doc_text">
				1014
				1015	<p>Hard fast rule: Preincrement (<tt>++X</tt>) may be no slower than
				1016	postincrement (<tt>X++</tt>) and could very well be a lot faster than it. Use
				1017	preincrementation whenever possible.</p>
				1018
				1019	<p>The semantics of postincrement include making a copy of the value being
				1020	incremented, returning it, and then preincrementing the "work value". For
				1021	primitive types, this isn't a big deal... but for iterators, it can be a huge
				1022	issue (for example, some iterators contains stack and set objects in them...
				1023	copying an iterator could invoke the copy ctor's of these as well). In general,
				1024	get in the habit of always using preincrement, and you won't have a problem.</p>
				1025
				1026	</div>
				1027
				1028	<!-- _______________________________________________________________________ -->
				1029	<div class="doc_subsubsection">
				1030	<a name="micro_namespaceindent">Namespace Indentation</a>
				1031	</div>
				1032
				1033	<div class="doc_text">
				1034
				1035	<p>
				1036	In general, we strive to reduce indentation where ever possible. This is useful
				1037	because we want code to <a href="#scf_codewidth">fit into 80 columns</a> without
				1038	wrapping horribly, but also because it makes it easier to understand the code.
				1039	Namespaces are a funny thing: they are often large, and we often desire to put
				1040	lots of stuff into them (so they can be large). Other times they are tiny,
				1041	because they just hold an enum or something similar. In order to balance this,
				1042	we use different approaches for small versus large namespaces.
				1043	</p>
				1044
				1045	<p>
				1046	If a namespace definition is small and <em>easily</em> fits on a screen (say,
				1047	less than 35 lines of code), then you should indent its body. Here's an
				1048	example:
				1049	</p>
				1050
				1051	<div class="doc_code">
				1052	<pre>
				1053	/// SomeCrazyThing - This namespace contains flags for ...
				1054	namespace SomeCrazyThing {
				1055	enum foo {
				1056	/// X - This is the X flag, which is ...
				1057	X = 1,
				1058
				1059	/// Y - This is the Y flag, which is ...
				1060	Y = 2,
				1061
				1062	/// Z - This is the Z flag, which is ...
				1063	Z = 4,
				1064
				1065	/// ALL_FLAGS - This is the union of all flags.
				1066	ALL_FLAGS = 7
				1067	};
				1068	}
				1069	</pre>
				1070	</div>
				1071
				1072	<p>Since the body is small, indenting adds value because it makes it very clear
				1073	where the namespace starts and ends, and it is easy to take the whole thing in
				1074	in one "gulp" when reading the code. If the blob of code in the namespace is
				1075	larger (as it typically is in a header in the llvm or clang namespaces), do not
				1076	indent the code, and add a comment indicating what namespace is being closed.
				1077	For example:</p>
				1078
				1079	<div class="doc_code">
				1080	<pre>
				1081	namespace llvm {
				1082	namespace knowledge {
				1083
				1084	/// Grokable - This class represents things that Smith can have an intimate
				1085	/// understanding of and contains the data associated with it.
				1086	class Grokable {
				1087	...
				1088	public:
				1089	explicit Grokable() { ... }
				1090	virtual ~Grokable() = 0;
				1091
				1092	...
				1093
				1094	};
				1095
				1096	} // end namespace knowledge
				1097	} // end namespace llvm
				1098	</pre>
				1099	</div>
				1100
				1101	<p>Because the class is large, we don't expect that the reader can easily
				1102	understand the entire concept in a glance, and the end of the file (where the
				1103	namespaces end) may be a long ways away from the place they open. As such,
				1104	indenting the contents of the namespace doesn't add any value, and detracts from
				1105	the readability of the class. In these cases it is best to <em>not</em> indent
				1106	the contents of the namespace.</p>
				1107
				1108	</div>
				1109
				1110	<!-- _______________________________________________________________________ -->
				1111	<div class="doc_subsubsection">
				1112	<a name="micro_anonns">Anonymous Namespaces</a>
				1113	</div>
				1114
				1115	<div class="doc_text">
				1116
				1117	<p>A common topic after talking about namespaces is anonymous namespaces.
				1118	Anonymous namespaces are a great language feature that tells the C++ compiler
				1119	that the contents of the namespace are only visible within the current
				1120	translation unit, allowing more aggressive optimization and eliminating the
				1121	possibility of symbol name collisions. Anonymous namespaces are to C++ as
				1122	"static" is to C functions and global variables. While "static" is available
				1123	in C++, anonymous namespaces are more general: they can make entire classes
				1124	private to a file.</p>
				1125
				1126	<p>The problem with anonymous namespaces is that they naturally want to
				1127	encourage indentation of their body, and they reduce locality of reference: if
				1128	you see a random function definition in a C++ file, it is easy to see if it is
				1129	marked static, but seeing if it is in an anonymous namespace requires scanning
				1130	a big chunk of the file.</p>
				1131
				1132	<p>Because of this, we have a simple guideline: make anonymous namespaces as
				1133	small as possible, and only use them for class declarations. For example, this
				1134	is good:</p>
				1135
				1136	<div class="doc_code">
				1137	<pre>
				1138	<b>namespace {</b>
				1139	class StringSort {
				1140	...
				1141	public:
				1142	StringSort(...)
				1143	bool operator<(const char *RHS) const;
				1144	};
				1145	<b>} // end anonymous namespace</b>
				1146
				1147	static void Helper() {
				1148	...
				1149	}
				1150
				1151	bool StringSort::operator<(const char *RHS) const {
				1152	...
				1153	}
				1154
				1155	</pre>
				1156	</div>
				1157
				1158	<p>This is bad:</p>
				1159
				1160
				1161	<div class="doc_code">
				1162	<pre>
				1163	<b>namespace {</b>
				1164	class StringSort {
				1165	...
				1166	public:
				1167	StringSort(...)
				1168	bool operator<(const char *RHS) const;
				1169	};
				1170
				1171	void Helper() {
				1172	...
				1173	}
				1174
				1175	bool StringSort::operator<(const char *RHS) const {
				1176	...
				1177	}
				1178
				1179	<b>} // end anonymous namespace</b>
				1180
				1181	</pre>
				1182	</div>
				1183
				1184
				1185	<p>This is bad specifically because if you're looking at "Helper" in the middle
				1186	of a large C++ file, that you have no immediate way to tell if it is local to
				1187	the file. When it is marked static explicitly, this is immediately obvious.
				1188	Also, there is no reason to enclose the definition of "operator<" in the
				1189	namespace since it was declared there.
				1190	</p>
				1191
				1192	</div>
				1193
				1194
				1195
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1196	<!-- *********************************************************************** -->
				1197	<div class="doc_section">
				1198	<a name="seealso">See Also</a>
				1199	</div>
				1200	<!-- *********************************************************************** -->
				1201
				1202	<div class="doc_text">
				1203
				1204	<p>A lot of these comments and recommendations have been culled for other
				1205	sources. Two particularly important books for our work are:</p>
				1206
				1207	<ol>
				1208
Chris Lattner	b5955b7	2007-11-09 21:49:08 +0000	[diff] [blame]	1209	<li><a href="http://www.amazon.com/Effective-Specific-Addison-Wesley-Professional-Computing/dp/0321334876">Effective
				1210	C++</a> by Scott Meyers. Also
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1211	interesting and useful are "More Effective C++" and "Effective STL" by the same
				1212	author.</li>
				1213
Chris Lattner	b5955b7	2007-11-09 21:49:08 +0000	[diff] [blame]	1214	<li>Large-Scale C++ Software Design by John Lakos</li>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1215
				1216	</ol>
				1217
				1218	<p>If you get some free time, and you haven't read them: do so, you might learn
				1219	something.</p>
				1220
				1221	</div>
				1222
				1223	<!-- *********************************************************************** -->
				1224
				1225	<hr>
				1226	<address>
				1227	<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
Misha Brukman	947321d	2008-12-11 17:34:48 +0000	[diff] [blame]	1228	src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS"></a>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1229	<a href="http://validator.w3.org/check/referer"><img
Misha Brukman	947321d	2008-12-11 17:34:48 +0000	[diff] [blame]	1230	src="http://www.w3.org/Icons/valid-html401-blue" alt="Valid HTML 4.01"></a>
Dan Gohman	f17a25c	2007-07-18 16:29:46 +0000	[diff] [blame]	1231
				1232	<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
				1233	<a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
				1234	Last modified: $Date$
				1235	</address>
				1236
				1237	</body>
				1238	</html>