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