2003-10-25 01:57:33 +08:00
|
|
|
<!DOCTYPE HTML PUBLIC "-//W3C//DTD HTML 4.01//EN"
|
|
|
|
|
"http://www.w3.org/TR/html4/strict.dtd">
|
|
|
|
|
<html>
|
|
|
|
|
<head>
|
|
|
|
|
<link rel="stylesheet" href="llvm.css" type="text/css">
|
|
|
|
|
<title>A Few Coding Standards</title>
|
|
|
|
|
</head>
|
|
|
|
|
<body>
|
|
|
|
|
|
|
|
|
|
<div class="doc_title">
|
|
|
|
|
A Few Coding Standards
|
|
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
<ol>
|
2003-10-25 01:57:33 +08:00
|
|
|
<li><a href="#introduction">Introduction</a></li>
|
2001-07-24 04:40:41 +08:00
|
|
|
<li><a href="#mechanicalissues">Mechanical Source Issues</a>
|
2001-07-09 11:27:08 +08:00
|
|
|
<ol>
|
|
|
|
|
<li><a href="#sourceformating">Source Code Formatting</a>
|
2003-10-25 01:57:33 +08:00
|
|
|
<ol>
|
|
|
|
|
<li><a href="#scf_commenting">Commenting</a></li>
|
|
|
|
|
<li><a href="#scf_commentformat">Comment Formatting</a></li>
|
2004-10-27 00:18:43 +08:00
|
|
|
<li><a href="#scf_includes"><tt>#include</tt> Style</a></li>
|
2003-10-25 01:57:33 +08:00
|
|
|
<li><a href="#scf_codewidth">Source Code Width</a></li>
|
|
|
|
|
<li><a href="#scf_spacestabs">Use Spaces Instead of Tabs</a></li>
|
|
|
|
|
<li><a href="#scf_indentation">Indent Code Consistently</a></li>
|
|
|
|
|
</ol></li>
|
2001-07-09 11:27:08 +08:00
|
|
|
<li><a href="#compilerissues">Compiler Issues</a>
|
|
|
|
|
<ol>
|
2003-10-25 01:57:33 +08:00
|
|
|
<li><a href="#ci_warningerrors">Treat Compiler Warnings Like
|
|
|
|
|
Errors</a></li>
|
|
|
|
|
<li><a href="#ci_portable_code">Write Portable Code</a></li>
|
2004-09-24 00:03:48 +08:00
|
|
|
<li><a href="#ci_class_struct">Use of class/struct Keywords</a></li>
|
2003-10-25 01:57:33 +08:00
|
|
|
</ol></li>
|
|
|
|
|
</ol></li>
|
2001-07-09 11:27:08 +08:00
|
|
|
<li><a href="#styleissues">Style Issues</a>
|
|
|
|
|
<ol>
|
|
|
|
|
<li><a href="#macro">The High Level Issues</a>
|
|
|
|
|
<ol>
|
2003-10-25 01:57:33 +08:00
|
|
|
<li><a href="#hl_module">A Public Header File <b>is</b> a
|
|
|
|
|
Module</a></li>
|
|
|
|
|
<li><a href="#hl_dontinclude">#include as Little as Possible</a></li>
|
|
|
|
|
<li><a href="#hl_privateheaders">Keep "internal" Headers
|
|
|
|
|
Private</a></li>
|
2006-12-09 09:20:34 +08:00
|
|
|
<li><a href="#ll_iostream"><tt>#include <iostream></tt> is
|
|
|
|
|
<em>forbidden</em></a></li>
|
2003-10-25 01:57:33 +08:00
|
|
|
</ol></li>
|
2001-07-09 11:27:08 +08:00
|
|
|
<li><a href="#micro">The Low Level Issues</a>
|
|
|
|
|
<ol>
|
2006-07-27 12:24:14 +08:00
|
|
|
<li><a href="#ll_assert">Assert Liberally</a></li>
|
|
|
|
|
<li><a href="#ll_ns_std">Do not use 'using namespace std'</a></li>
|
2006-12-09 09:20:34 +08:00
|
|
|
<li><a href="#ll_virtual_anch">Provide a virtual method anchor for
|
2006-12-09 09:35:43 +08:00
|
|
|
classes in headers</a></li>
|
2006-07-27 12:24:14 +08:00
|
|
|
<li><a href="#ll_preincrement">Prefer Preincrement</a></li>
|
|
|
|
|
<li><a href="#ll_avoidendl">Avoid <tt>std::endl</tt></a></li>
|
2003-10-25 01:57:33 +08:00
|
|
|
</ol></li>
|
|
|
|
|
</ol></li>
|
|
|
|
|
<li><a href="#seealso">See Also</a></li>
|
|
|
|
|
</ol>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2004-05-24 05:05:07 +08:00
|
|
|
<div class="doc_author">
|
2006-12-09 09:20:34 +08:00
|
|
|
<p>Written by <a href="mailto:sabre@nondot.org">Chris Lattner</a> and
|
|
|
|
|
<a href="mailto:void@nondot.org">Bill Wendling</a></p>
|
2004-05-24 05:05:07 +08:00
|
|
|
</div>
|
|
|
|
|
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_section">
|
|
|
|
|
<a name="introduction">Introduction</a>
|
|
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_text">
|
|
|
|
|
|
|
|
|
|
<p>This document attempts to describe a few coding standards that are being used
|
|
|
|
|
in the LLVM source tree. Although no coding standards should be regarded as
|
2003-10-07 03:26:00 +08:00
|
|
|
absolute requirements to be followed in all instances, coding standards can be
|
2003-10-25 01:57:33 +08:00
|
|
|
useful.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>This document intentionally does not prescribe fixed standards for religious
|
2003-10-07 03:26:00 +08:00
|
|
|
issues such as brace placement and space usage. For issues like this, follow
|
2003-10-25 01:57:33 +08:00
|
|
|
the golden rule:</p>
|
|
|
|
|
|
|
|
|
|
<blockquote>
|
|
|
|
|
|
|
|
|
|
<p><b><a name="goldenrule">If you are adding a significant body of source to a
|
|
|
|
|
project, feel free to use whatever style you are most comfortable with. If you
|
|
|
|
|
are extending, enhancing, or bug fixing already implemented code, use the style
|
|
|
|
|
that is already being used so that the source is uniform and easy to
|
|
|
|
|
follow.</a></b></p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
</blockquote>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>The ultimate goal of these guidelines is the increase readability and
|
2003-10-07 03:26:00 +08:00
|
|
|
maintainability of our common source base. If you have suggestions for topics to
|
2003-10-25 01:57:33 +08:00
|
|
|
be included, please mail them to <a
|
|
|
|
|
href="mailto:sabre@nondot.org">Chris</a>.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_section">
|
|
|
|
|
<a name="mechanicalissues">Mechanical Source Issues</a>
|
|
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<!-- ======================================================================= -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="sourceformating">Source Code Formatting</a>
|
|
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="scf_commenting">Commenting</a>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>Comments are one critical part of readability and maintainability. Everyone
|
2004-12-04 08:32:12 +08:00
|
|
|
knows they should comment, so should you. Although we all should probably
|
2003-10-07 03:26:00 +08:00
|
|
|
comment our code more than we do, there are a few very critical places that
|
2003-10-25 01:57:33 +08:00
|
|
|
documentation is very useful:</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2004-05-24 05:05:07 +08:00
|
|
|
<b>File Headers</b>
|
2003-10-25 01:57:33 +08:00
|
|
|
|
2007-07-09 16:04:31 +08:00
|
|
|
<p>Every source file should have a header on it that describes the basic
|
|
|
|
|
purpose of the file. If a file does not have a header, it should not be
|
|
|
|
|
checked into Subversion. Most source trees will probably have a standard
|
2003-10-25 01:57:33 +08:00
|
|
|
file header format. The standard format for the LLVM source tree looks like
|
|
|
|
|
this:</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2004-07-29 06:31:54 +08:00
|
|
|
<div class="doc_code">
|
2001-07-09 11:27:08 +08:00
|
|
|
<pre>
|
2003-10-13 22:58:11 +08:00
|
|
|
//===-- llvm/Instruction.h - Instruction class definition -------*- C++ -*-===//
|
2004-05-24 05:05:07 +08:00
|
|
|
//
|
|
|
|
|
// The LLVM Compiler Infrastructure
|
|
|
|
|
//
|
2007-12-30 03:56:08 +08:00
|
|
|
// This file is distributed under the University of Illinois Open Source
|
|
|
|
|
// License. See LICENSE.TXT for details.
|
2004-05-24 05:05:07 +08:00
|
|
|
//
|
|
|
|
|
//===----------------------------------------------------------------------===//
|
2001-07-09 11:27:08 +08:00
|
|
|
//
|
|
|
|
|
// This file contains the declaration of the Instruction class, which is the
|
|
|
|
|
// base class for all of the VM instructions.
|
|
|
|
|
//
|
|
|
|
|
//===----------------------------------------------------------------------===//
|
|
|
|
|
</pre>
|
2004-07-29 06:31:54 +08:00
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2007-12-30 03:56:08 +08:00
|
|
|
<p>A few things to note about this particular format: The "<tt>-*- C++
|
2003-10-25 01:57:33 +08:00
|
|
|
-*-</tt>" string on the first line is there to tell Emacs that the source file
|
2004-07-29 06:37:57 +08:00
|
|
|
is a C++ file, not a C file (Emacs assumes .h files are C files by default).
|
|
|
|
|
Note that this tag is not necessary in .cpp files. The name of the file is also
|
|
|
|
|
on the first line, along with a very short description of the purpose of the
|
|
|
|
|
file. This is important when printing out code and flipping though lots of
|
|
|
|
|
pages.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2007-12-30 03:56:08 +08:00
|
|
|
<p>The next section in the file is a concise note that defines the license
|
|
|
|
|
that the file is released under. This makes it perfectly clear what terms the
|
|
|
|
|
source code can be distributed under and should not be modified in any way.</p>
|
2004-05-24 05:05:07 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>The main body of the description does not have to be very long in most cases.
|
2003-10-07 03:26:00 +08:00
|
|
|
Here it's only two lines. If an algorithm is being implemented or something
|
|
|
|
|
tricky is going on, a reference to the paper where it is published should be
|
2003-10-25 01:57:33 +08:00
|
|
|
included, as well as any notes or "gotchas" in the code to watch out for.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2004-05-24 05:05:07 +08:00
|
|
|
<b>Class overviews</b>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2006-08-01 04:18:49 +08:00
|
|
|
<p>Classes are one fundamental part of a good object oriented design. As such,
|
2003-10-25 01:57:33 +08:00
|
|
|
a class definition should have a comment block that explains what the class is
|
2003-10-07 03:26:00 +08:00
|
|
|
used for... if it's not obvious. If it's so completely obvious your grandma
|
|
|
|
|
could figure it out, it's probably safe to leave it out. Naming classes
|
2004-12-04 08:32:12 +08:00
|
|
|
something sane goes a long ways towards avoiding writing documentation.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
|
2004-05-24 05:05:07 +08:00
|
|
|
<b>Method information</b>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>Methods defined in a class (as well as any global functions) should also be
|
2003-10-07 03:26:00 +08:00
|
|
|
documented properly. A quick note about what it does any a description of the
|
|
|
|
|
borderline behaviour is all that is necessary here (unless something
|
|
|
|
|
particularly tricky or insideous is going on). The hope is that people can
|
|
|
|
|
figure out how to use your interfaces without reading the code itself... that is
|
2003-10-25 01:57:33 +08:00
|
|
|
the goal metric.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>Good things to talk about here are what happens when something unexpected
|
|
|
|
|
happens: does the method return null? Abort? Format your hard disk?</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="scf_commentformat">Comment Formatting</a>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>In general, prefer C++ style (<tt>//</tt>) comments. They take less space,
|
2003-10-07 03:26:00 +08:00
|
|
|
require less typing, don't have nesting problems, etc. There are a few cases
|
2003-10-25 01:57:33 +08:00
|
|
|
when it is useful to use C style (<tt>/* */</tt>) comments however:</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
<ol>
|
2003-10-25 01:57:33 +08:00
|
|
|
<li>When writing a C code: Obviously if you are writing C code, use C style
|
2004-12-04 08:32:12 +08:00
|
|
|
comments.</li>
|
2004-10-27 00:18:43 +08:00
|
|
|
<li>When writing a header file that may be <tt>#include</tt>d by a C source
|
|
|
|
|
file.</li>
|
2003-10-25 01:57:33 +08:00
|
|
|
<li>When writing a source file that is used by a tool that only accepts C
|
|
|
|
|
style comments.</li>
|
|
|
|
|
</ol>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>To comment out a large block of code, use <tt>#if 0</tt> and <tt>#endif</tt>.
|
|
|
|
|
These nest properly and are better behaved in general than C style comments.</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-08-08 05:45:47 +08:00
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_subsubsection">
|
2004-10-27 00:18:43 +08:00
|
|
|
<a name="scf_includes"><tt>#include</tt> Style</a>
|
2003-10-25 01:57:33 +08:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2003-08-08 05:45:47 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>Immediately after the <a href="#scf_commenting">header file comment</a> (and
|
2003-08-08 05:45:47 +08:00
|
|
|
include guards if working on a header file), the <a
|
2004-07-29 06:31:54 +08:00
|
|
|
href="#hl_dontinclude">minimal</a> list of <tt>#include</tt>s required by the
|
|
|
|
|
file should be listed. We prefer these <tt>#include</tt>s to be listed in this
|
|
|
|
|
order:</p>
|
2003-08-08 05:45:47 +08:00
|
|
|
|
|
|
|
|
<ol>
|
2003-10-25 01:57:33 +08:00
|
|
|
<li><a href="#mmheader">Main Module header</a></li>
|
|
|
|
|
<li><a href="#hl_privateheaders">Local/Private Headers</a></li>
|
2004-07-29 06:31:54 +08:00
|
|
|
<li><tt>llvm/*</tt></li>
|
|
|
|
|
<li><tt>llvm/Analysis/*</tt></li>
|
|
|
|
|
<li><tt>llvm/Assembly/*</tt></li>
|
|
|
|
|
<li><tt>llvm/Bytecode/*</tt></li>
|
|
|
|
|
<li><tt>llvm/CodeGen/*</tt></li>
|
2003-10-25 01:57:33 +08:00
|
|
|
<li>...</li>
|
2004-07-29 06:31:54 +08:00
|
|
|
<li><tt>Support/*</tt></li>
|
|
|
|
|
<li><tt>Config/*</tt></li>
|
|
|
|
|
<li>System <tt>#includes</tt></li>
|
2003-08-08 05:45:47 +08:00
|
|
|
</ol>
|
|
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>... and each catagory should be sorted by name.</p>
|
2003-08-08 05:45:47 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p><a name="mmheader">The "Main Module Header"</a> file applies to .cpp file
|
2004-10-27 00:18:43 +08:00
|
|
|
which implement an interface defined by a .h file. This <tt>#include</tt>
|
|
|
|
|
should always be included <b>first</b> regardless of where it lives on the file
|
|
|
|
|
system. By including a header file first in the .cpp files that implement the
|
|
|
|
|
interfaces, we ensure that the header does not have any hidden dependencies
|
|
|
|
|
which are not explicitly #included in the header, but should be. It is also a
|
|
|
|
|
form of documentation in the .cpp file to indicate where the interfaces it
|
|
|
|
|
implements are defined.</p>
|
2003-08-08 05:45:47 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="scf_codewidth">Source Code Width</a>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>Write your code to fit within 80 columns of text. This helps those of us who
|
|
|
|
|
like to print out code and look at your code in an xterm without resizing
|
|
|
|
|
it.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="scf_spacestabs">Use Spaces Instead of Tabs</a>
|
|
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_text">
|
|
|
|
|
|
|
|
|
|
<p>In all cases, prefer spaces to tabs in source files. People have different
|
2003-10-07 03:26:00 +08:00
|
|
|
prefered indentation levels, and different styles of indentation that they
|
|
|
|
|
like... this is fine. What isn't is that different editors/viewers expand tabs
|
|
|
|
|
out to different tab stops. This can cause your code to look completely
|
2003-10-25 01:57:33 +08:00
|
|
|
unreadable, and it is not worth dealing with.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>As always, follow the <a href="#goldenrule">Golden Rule</a> above: follow the
|
2003-10-07 03:26:00 +08:00
|
|
|
style of existing code if your are modifying and extending it. If you like four
|
|
|
|
|
spaces of indentation, <b>DO NOT</b> do that in the middle of a chunk of code
|
|
|
|
|
with two spaces of indentation. Also, do not reindent a whole source file: it
|
2003-10-25 01:57:33 +08:00
|
|
|
makes for incredible diffs that are absolutely worthless.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="scf_indentation">Indent Code Consistently</a>
|
|
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_text">
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>Okay, your first year of programming you were told that indentation is
|
|
|
|
|
important. If you didn't believe and internalize this then, now is the time.
|
|
|
|
|
Just do it.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ======================================================================= -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="compilerissues">Compiler Issues</a>
|
|
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="ci_warningerrors">Treat Compiler Warnings Like Errors</a>
|
|
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_text">
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>If your code has compiler warnings in it, something is wrong: you aren't
|
|
|
|
|
casting values correctly, your have "questionable" constructs in your code, or
|
|
|
|
|
you are doing something legitimately wrong. Compiler warnings can cover up
|
|
|
|
|
legitimate errors in output and make dealing with a translation unit
|
|
|
|
|
difficult.</p>
|
|
|
|
|
|
|
|
|
|
<p>It is not possible to prevent all warnings from all compilers, nor is it
|
2003-10-07 03:26:00 +08:00
|
|
|
desirable. Instead, pick a standard compiler (like <tt>gcc</tt>) that provides
|
|
|
|
|
a good thorough set of warnings, and stick to them. At least in the case of
|
|
|
|
|
<tt>gcc</tt>, it is possible to work around any spurious errors by changing the
|
|
|
|
|
syntax of the code slightly. For example, an warning that annoys me occurs when
|
2003-10-25 01:57:33 +08:00
|
|
|
I write code like this:</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2004-07-29 06:31:54 +08:00
|
|
|
<div class="doc_code">
|
2001-07-09 11:27:08 +08:00
|
|
|
<pre>
|
2004-07-29 06:31:54 +08:00
|
|
|
if (V = getValue()) {
|
|
|
|
|
...
|
|
|
|
|
}
|
2003-10-25 01:57:33 +08:00
|
|
|
</pre>
|
2004-07-29 06:31:54 +08:00
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p><tt>gcc</tt> will warn me that I probably want to use the <tt>==</tt>
|
|
|
|
|
operator, and that I probably mistyped it. In most cases, I haven't, and I
|
|
|
|
|
really don't want the spurious errors. To fix this particular problem, I
|
|
|
|
|
rewrite the code like this:</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2004-07-29 06:31:54 +08:00
|
|
|
<div class="doc_code">
|
2001-07-09 11:27:08 +08:00
|
|
|
<pre>
|
2004-07-29 06:31:54 +08:00
|
|
|
if ((V = getValue())) {
|
|
|
|
|
...
|
|
|
|
|
}
|
2003-10-25 01:57:33 +08:00
|
|
|
</pre>
|
2004-07-29 06:31:54 +08:00
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>...which shuts <tt>gcc</tt> up. Any <tt>gcc</tt> warning that annoys you can
|
|
|
|
|
be fixed by massaging the code appropriately.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>These are the <tt>gcc</tt> warnings that I prefer to enable: <tt>-Wall
|
|
|
|
|
-Winline -W -Wwrite-strings -Wno-unused</tt></p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="ci_portable_code">Write Portable Code</a>
|
|
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_text">
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>In almost all cases, it is possible and within reason to write completely
|
|
|
|
|
portable code. If there are cases where it isn't possible to write portable
|
|
|
|
|
code, isolate it behind a well defined (and well documented) interface.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>In practice, this means that you shouldn't assume much about the host
|
|
|
|
|
compiler, including its support for "high tech" features like partial
|
|
|
|
|
specialization of templates. In fact, Visual C++ 6 could be an important target
|
|
|
|
|
for our work in the future, and we don't want to have to rewrite all of our code
|
|
|
|
|
to support it.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2004-09-24 00:03:48 +08:00
|
|
|
<!-- _______________________________________________________________________ -->
|
|
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="ci_class_struct">Use of <tt>class</tt> and <tt>struct</tt> Keywords</a>
|
|
|
|
|
</div>
|
|
|
|
|
<div class="doc_text">
|
2004-10-26 23:45:13 +08:00
|
|
|
|
|
|
|
|
<p>In C++, the <tt>class</tt> and <tt>struct</tt> keywords can be used almost
|
|
|
|
|
interchangeably. The only difference is when they are used to declare a class:
|
|
|
|
|
<tt>class</tt> makes all members private by default while <tt>struct</tt> makes
|
|
|
|
|
all members public by default.</p>
|
|
|
|
|
|
|
|
|
|
<p>Unfortunately, not all compilers follow the rules and some will generate
|
|
|
|
|
different symbols based on whether <tt>class</tt> or <tt>struct</tt> was used to
|
|
|
|
|
declare the symbol. This can lead to problems at link time.</p>
|
|
|
|
|
|
|
|
|
|
<p>So, the rule for LLVM is to always use the <tt>class</tt> keyword, unless
|
|
|
|
|
<b>all</b> members are public, in which case <tt>struct</tt> is allowed.</p>
|
|
|
|
|
|
2004-09-24 00:03:48 +08:00
|
|
|
</div>
|
|
|
|
|
|
2001-07-09 11:27:08 +08:00
|
|
|
<!-- *********************************************************************** -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_section">
|
|
|
|
|
<a name="styleissues">Style Issues</a>
|
|
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- ======================================================================= -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_subsection">
|
|
|
|
|
<a name="macro">The High Level Issues</a>
|
|
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="hl_module">A Public Header File <b>is</b> a Module</a>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>C++ doesn't do too well in the modularity department. There is no real
|
2003-07-29 05:57:18 +08:00
|
|
|
encapsulation or data hiding (unless you use expensive protocol classes), but it
|
|
|
|
|
is what we have to work with. When you write a public header file (in the LLVM
|
|
|
|
|
source tree, they live in the top level "include" directory), you are defining a
|
2003-10-25 01:57:33 +08:00
|
|
|
module of functionality.</p>
|
2003-07-29 05:57:18 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>Ideally, modules should be completely independent of each other, and their
|
2003-07-29 05:57:18 +08:00
|
|
|
header files should only include the absolute minimum number of headers
|
|
|
|
|
possible. A module is not just a class, a function, or a namespace: <a
|
|
|
|
|
href="http://www.cuj.com/articles/2000/0002/0002c/0002c.htm">it's a collection
|
|
|
|
|
of these</a> that defines an interface. This interface may be several
|
|
|
|
|
functions, classes or data structures, but the important issue is how they work
|
2003-10-25 01:57:33 +08:00
|
|
|
together.</p>
|
2003-07-29 05:57:18 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>In general, a module should be implemented with one or more <tt>.cpp</tt>
|
|
|
|
|
files. Each of these <tt>.cpp</tt> files should include the header that defines
|
|
|
|
|
their interface first. This ensure that all of the dependences of the module
|
|
|
|
|
header have been properly added to the module header itself, and are not
|
|
|
|
|
implicit. System headers should be included after user headers for a
|
|
|
|
|
translation unit.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_subsubsection">
|
2004-10-27 00:18:43 +08:00
|
|
|
<a name="hl_dontinclude"><tt>#include</tt> as Little as Possible</a>
|
2003-10-25 01:57:33 +08:00
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_text">
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p><tt>#include</tt> hurts compile time performance. Don't do it unless you
|
|
|
|
|
have to, especially in header files.</p>
|
|
|
|
|
|
|
|
|
|
<p>But wait, sometimes you need to have the definition of a class to use it, or
|
2004-10-27 00:18:43 +08:00
|
|
|
to inherit from it. In these cases go ahead and <tt>#include</tt> that header
|
|
|
|
|
file. Be aware however that there are many cases where you don't need to have
|
|
|
|
|
the full definition of a class. If you are using a pointer or reference to a
|
|
|
|
|
class, you don't need the header file. If you are simply returning a class
|
|
|
|
|
instance from a prototyped function or method, you don't need it. In fact, for
|
|
|
|
|
most cases, you simply don't need the definition of a class... and not
|
|
|
|
|
<tt>#include</tt>'ing speeds up compilation.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>It is easy to try to go too overboard on this recommendation, however. You
|
2007-02-11 02:35:31 +08:00
|
|
|
<b>must</b> include all of the header files that you are using -- you can
|
|
|
|
|
include them either directly
|
2003-07-29 05:57:18 +08:00
|
|
|
or indirectly (through another header file). To make sure that you don't
|
|
|
|
|
accidently forget to include a header file in your module header, make sure to
|
|
|
|
|
include your module header <b>first</b> in the implementation file (as mentioned
|
|
|
|
|
above). This way there won't be any hidden dependencies that you'll find out
|
2003-10-25 01:57:33 +08:00
|
|
|
about later...</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="hl_privateheaders">Keep "internal" Headers Private</a>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>Many modules have a complex implementation that causes them to use more than
|
|
|
|
|
one implementation (<tt>.cpp</tt>) file. It is often tempting to put the
|
|
|
|
|
internal communication interface (helper classes, extra functions, etc) in the
|
2004-12-04 08:32:12 +08:00
|
|
|
public module header file. Don't do this.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>If you really need to do something like this, put a private header file in
|
|
|
|
|
the same directory as the source files, and include it locally. This ensures
|
|
|
|
|
that your private interface remains private and undisturbed by outsiders.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>Note however, that it's okay to put extra implementation methods a public
|
|
|
|
|
class itself... just make them private (or protected), and all is well.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2006-12-09 09:20:34 +08:00
|
|
|
<!-- _______________________________________________________________________ -->
|
|
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="ll_iostream"><tt>#include <iostream></tt> is forbidden</a>
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
|
|
|
|
|
<p>The use of <tt>#include <iostream></tt> in library files is
|
|
|
|
|
hereby <b><em>forbidden</em></b>. The primary reason for doing this is to
|
|
|
|
|
support clients using LLVM libraries as part of larger systems. In particular,
|
|
|
|
|
we statically link LLVM into some dynamic libraries. Even if LLVM isn't used,
|
|
|
|
|
the static c'tors are run whenever an application start up that uses the dynamic
|
|
|
|
|
library. There are two problems with this:</p>
|
|
|
|
|
|
|
|
|
|
<ol>
|
|
|
|
|
<li>The time to run the static c'tors impacts startup time of
|
2007-11-06 17:36:34 +08:00
|
|
|
applications—a critical time for GUI apps.</li>
|
2006-12-09 09:20:34 +08:00
|
|
|
<li>The static c'tors cause the app to pull many extra pages of memory off the
|
2007-11-06 17:36:34 +08:00
|
|
|
disk: both the code for the static c'tors in each <tt>.o</tt> file and the
|
|
|
|
|
small amount of data that gets touched. In addition, touched/dirty pages
|
|
|
|
|
put more pressure on the VM system on low-memory machines.</li>
|
2006-12-09 09:20:34 +08:00
|
|
|
</ol>
|
|
|
|
|
|
2007-11-06 17:36:34 +08:00
|
|
|
<div align="center">
|
2007-09-22 18:03:25 +08:00
|
|
|
<table>
|
2006-12-09 09:20:34 +08:00
|
|
|
<tbody>
|
|
|
|
|
<tr>
|
|
|
|
|
<th>Old Way</th>
|
|
|
|
|
<th>New Way</th>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td align="left"><pre>#include <iostream></pre></td>
|
|
|
|
|
<td align="left"><pre>#include "llvm/Support/Streams.h"</pre></td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
2006-12-17 19:40:40 +08:00
|
|
|
<td align="left"><pre>DEBUG(std::cerr << ...);
|
|
|
|
|
DEBUG(dump(std::cerr));</pre></td>
|
|
|
|
|
<td align="left"><pre>DOUT << ...;
|
2007-11-06 17:36:34 +08:00
|
|
|
DEBUG(dump(DOUT));</pre></td>
|
2006-12-09 09:20:34 +08:00
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td align="left"><pre>std::cerr << "Hello world\n";</pre></td>
|
|
|
|
|
<td align="left"><pre>llvm::cerr << "Hello world\n";</pre></td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td align="left"><pre>std::cout << "Hello world\n";</pre></td>
|
|
|
|
|
<td align="left"><pre>llvm::cout << "Hello world\n";</pre></td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td align="left"><pre>std::cin >> Var;</pre></td>
|
|
|
|
|
<td align="left"><pre>llvm::cin >> Var;</pre></td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td align="left"><pre>std::ostream</pre></td>
|
|
|
|
|
<td align="left"><pre>llvm::OStream</pre></td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td align="left"><pre>std::istream</pre></td>
|
|
|
|
|
<td align="left"><pre>llvm::IStream</pre></td>
|
|
|
|
|
</tr>
|
|
|
|
|
<tr>
|
|
|
|
|
<td align="left"><pre>std::stringstream</pre></td>
|
|
|
|
|
<td align="left"><pre>llvm::StringStream</pre></td>
|
|
|
|
|
</tr>
|
2006-12-09 09:27:51 +08:00
|
|
|
<tr>
|
2007-09-22 18:03:25 +08:00
|
|
|
<td align="left"><pre>void print(std::ostream &Out);
|
2006-12-09 09:27:51 +08:00
|
|
|
// ...
|
|
|
|
|
print(std::cerr);</pre></td>
|
2007-11-06 17:36:34 +08:00
|
|
|
<td align="left"><pre>void print(llvm::OStream Out);<sup>1</sup>
|
2006-12-09 09:27:51 +08:00
|
|
|
// ...
|
2006-12-17 19:40:40 +08:00
|
|
|
print(llvm::cerr);</pre>
|
|
|
|
|
|
2007-11-06 17:36:34 +08:00
|
|
|
</td> </tbody> </table>
|
|
|
|
|
</div>
|
|
|
|
|
|
2007-09-22 18:03:25 +08:00
|
|
|
<div class="doc_text">
|
2007-11-06 17:36:34 +08:00
|
|
|
<p><sup>1</sup><tt>llvm::OStream</tt> is a light-weight class so it should never
|
|
|
|
|
be passed by reference. This is important because in some configurations,
|
|
|
|
|
<tt>DOUT</tt> is an rvalue.</p>
|
2007-09-22 18:03:25 +08:00
|
|
|
</div>
|
2006-12-09 09:20:34 +08:00
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
2001-07-09 11:27:08 +08:00
|
|
|
<!-- ======================================================================= -->
|
2004-05-24 05:05:07 +08:00
|
|
|
<div class="doc_subsection">
|
2003-10-25 01:57:33 +08:00
|
|
|
<a name="micro">The Low Level Issues</a>
|
|
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_subsubsection">
|
2006-07-27 12:24:14 +08:00
|
|
|
<a name="ll_assert">Assert Liberally</a>
|
2003-10-25 01:57:33 +08:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>Use the "<tt>assert</tt>" function to its fullest. Check all of your
|
2003-07-29 05:57:18 +08:00
|
|
|
preconditions and assumptions, you never know when a bug (not neccesarily even
|
|
|
|
|
yours) might be caught early by an assertion, which reduces debugging time
|
|
|
|
|
dramatically. The "<tt><cassert></tt>" header file is probably already
|
|
|
|
|
included by the header files you are using, so it doesn't cost anything to use
|
2003-10-25 01:57:33 +08:00
|
|
|
it.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>To further assist with debugging, make sure to put some kind of error message
|
|
|
|
|
in the assertion statement (which is printed if the assertion is tripped). This
|
2003-07-29 05:57:18 +08:00
|
|
|
helps the poor debugging make sense of why an assertion is being made and
|
2003-10-25 01:57:33 +08:00
|
|
|
enforced, and hopefully what to do about it. Here is one complete example:</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2004-07-29 06:31:54 +08:00
|
|
|
<div class="doc_code">
|
2001-07-09 11:27:08 +08:00
|
|
|
<pre>
|
2004-07-29 06:31:54 +08:00
|
|
|
inline Value *getOperand(unsigned i) {
|
|
|
|
|
assert(i < Operands.size() && "getOperand() out of range!");
|
|
|
|
|
return Operands[i];
|
|
|
|
|
}
|
2001-07-09 11:27:08 +08:00
|
|
|
</pre>
|
2004-07-29 06:31:54 +08:00
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>Here are some examples:</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2004-07-29 06:31:54 +08:00
|
|
|
<div class="doc_code">
|
2001-07-09 11:27:08 +08:00
|
|
|
<pre>
|
2004-07-29 06:31:54 +08:00
|
|
|
assert(Ty->isPointerType() && "Can't allocate a non pointer type!");
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2004-07-29 06:31:54 +08:00
|
|
|
assert((Opcode == Shl || Opcode == Shr) && "ShiftInst Opcode invalid!");
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2004-07-29 06:31:54 +08:00
|
|
|
assert(idx < getNumSuccessors() && "Successor # out of range!");
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2004-07-29 06:31:54 +08:00
|
|
|
assert(V1.getType() == V2.getType() && "Constant types must be identical!");
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2004-07-29 06:31:54 +08:00
|
|
|
assert(isa<PHINode>(Succ->front()) && "Only works on PHId BBs!");
|
2003-10-25 01:57:33 +08:00
|
|
|
</pre>
|
2004-07-29 06:31:54 +08:00
|
|
|
</div>
|
2003-10-25 01:57:33 +08:00
|
|
|
|
|
|
|
|
<p>You get the idea...</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2006-01-02 05:59:22 +08:00
|
|
|
<!-- _______________________________________________________________________ -->
|
|
|
|
|
<div class="doc_subsubsection">
|
2006-12-09 09:35:43 +08:00
|
|
|
<a name="ll_ns_std">Do not use '<tt>using namespace std</tt>'</a>
|
2006-01-02 05:59:22 +08:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
<p>In LLVM, we prefer to explicitly prefix all identifiers from the standard
|
2006-12-09 09:35:43 +08:00
|
|
|
namespace with an "<tt>std::</tt>" prefix, rather than rely on
|
|
|
|
|
"<tt>using namespace std;</tt>".</p>
|
|
|
|
|
|
|
|
|
|
<p> In header files, adding a '<tt>using namespace XXX</tt>' directive pollutes
|
|
|
|
|
the namespace of any source file that includes the header. This is clearly a
|
|
|
|
|
bad thing.</p>
|
|
|
|
|
|
|
|
|
|
<p>In implementation files (e.g. .cpp files), the rule is more of a stylistic
|
|
|
|
|
rule, but is still important. Basically, using explicit namespace prefixes
|
|
|
|
|
makes the code <b>clearer</b>, because it is immediately obvious what facilities
|
|
|
|
|
are being used and where they are coming from, and <b>more portable</b>, because
|
|
|
|
|
namespace clashes cannot occur between LLVM code and other namespaces. The
|
|
|
|
|
portability rule is important because different standard library implementations
|
|
|
|
|
expose different symbols (potentially ones they shouldn't), and future revisions
|
|
|
|
|
to the C++ standard will add more symbols to the <tt>std</tt> namespace. As
|
|
|
|
|
such, we never use '<tt>using namespace std;</tt>' in LLVM.</p>
|
|
|
|
|
|
|
|
|
|
<p>The exception to the general rule (i.e. it's not an exception for
|
|
|
|
|
the <tt>std</tt> namespace) is for implementation files. For example, all of
|
|
|
|
|
the code in the LLVM project implements code that lives in the 'llvm' namespace.
|
|
|
|
|
As such, it is ok, and actually clearer, for the .cpp files to have a '<tt>using
|
|
|
|
|
namespace llvm</tt>' directive at their top, after the <tt>#include</tt>s. The
|
|
|
|
|
general form of this rule is that any .cpp file that implements code in any
|
|
|
|
|
namespace may use that namespace (and its parents'), but should not use any
|
|
|
|
|
others.</p>
|
2006-01-02 05:59:22 +08:00
|
|
|
|
|
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_subsubsection">
|
2006-12-09 09:35:43 +08:00
|
|
|
<a name="ll_virtual_anch">Provide a virtual method anchor for classes
|
|
|
|
|
in headers</a>
|
2006-07-27 12:24:14 +08:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
|
|
|
|
|
|
|
|
|
<p>If a class is defined in a header file and has a v-table (either it has
|
|
|
|
|
virtual methods or it derives from classes with virtual methods), it must
|
|
|
|
|
always have at least one out-of-line virtual method in the class. Without
|
|
|
|
|
this, the compiler will copy the vtable and RTTI into every .o file that
|
|
|
|
|
#includes the header, bloating .o file sizes and increasing link times.
|
|
|
|
|
</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
|
|
|
|
|
<!-- _______________________________________________________________________ -->
|
|
|
|
|
<div class="doc_subsubsection">
|
|
|
|
|
<a name="ll_preincrement">Prefer Preincrement</a>
|
2003-10-25 01:57:33 +08:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2004-07-29 06:31:54 +08:00
|
|
|
<p>Hard fast rule: Preincrement (<tt>++X</tt>) may be no slower than
|
|
|
|
|
postincrement (<tt>X++</tt>) and could very well be a lot faster than it. Use
|
|
|
|
|
preincrementation whenever possible.</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>The semantics of postincrement include making a copy of the value being
|
2003-07-29 05:57:18 +08:00
|
|
|
incremented, returning it, and then preincrementing the "work value". For
|
|
|
|
|
primitive types, this isn't a big deal... but for iterators, it can be a huge
|
|
|
|
|
issue (for example, some iterators contains stack and set objects in them...
|
|
|
|
|
copying an iterator could invoke the copy ctor's of these as well). In general,
|
2003-10-25 01:57:33 +08:00
|
|
|
get in the habit of always using preincrement, and you won't have a problem.</p>
|
|
|
|
|
|
|
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2002-01-21 03:01:26 +08:00
|
|
|
<!-- _______________________________________________________________________ -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_subsubsection">
|
2006-07-27 12:24:14 +08:00
|
|
|
<a name="ll_avoidendl">Avoid <tt>std::endl</tt></a>
|
2003-10-25 01:57:33 +08:00
|
|
|
</div>
|
|
|
|
|
|
|
|
|
|
<div class="doc_text">
|
2002-01-21 03:01:26 +08:00
|
|
|
|
2004-05-24 05:05:07 +08:00
|
|
|
<p>The <tt>std::endl</tt> modifier, when used with iostreams outputs a newline
|
|
|
|
|
to the output stream specified. In addition to doing this, however, it also
|
|
|
|
|
flushes the output stream. In other words, these are equivalent:</p>
|
2002-01-21 03:01:26 +08:00
|
|
|
|
2004-07-29 06:31:54 +08:00
|
|
|
<div class="doc_code">
|
2002-01-21 03:01:26 +08:00
|
|
|
<pre>
|
2004-07-29 06:31:54 +08:00
|
|
|
std::cout << std::endl;
|
|
|
|
|
std::cout << '\n' << std::flush;
|
2002-01-21 03:01:26 +08:00
|
|
|
</pre>
|
2004-07-29 06:31:54 +08:00
|
|
|
</div>
|
2002-01-21 03:01:26 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<p>Most of the time, you probably have no reason to flush the output stream, so
|
2004-07-29 06:31:54 +08:00
|
|
|
it's better to use a literal <tt>'\n'</tt>.</p>
|
2002-01-21 03:01:26 +08:00
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
</div>
|
2002-01-21 03:01:26 +08:00
|
|
|
|
2006-12-09 09:20:34 +08:00
|
|
|
|
2001-07-09 11:27:08 +08:00
|
|
|
<!-- *********************************************************************** -->
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_section">
|
|
|
|
|
<a name="seealso">See Also</a>
|
|
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
2003-10-25 01:57:33 +08:00
|
|
|
<div class="doc_text">
|
|
|
|
|
|
|
|
|
|
<p>A lot of these comments and recommendations have been culled for other
|
|
|
|
|
sources. Two particularly important books for our work are:</p>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
<ol>
|
|
|
|
|
|
2007-11-10 05:49:08 +08:00
|
|
|
<li><a href="http://www.amazon.com/Effective-Specific-Addison-Wesley-Professional-Computing/dp/0321334876">Effective
|
|
|
|
|
C++</a> by Scott Meyers. Also
|
2004-05-24 05:05:07 +08:00
|
|
|
interesting and useful are "More Effective C++" and "Effective STL" by the same
|
|
|
|
|
author.</li>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
2007-11-10 05:49:08 +08:00
|
|
|
<li>Large-Scale C++ Software Design by John Lakos</li>
|
2003-10-25 01:57:33 +08:00
|
|
|
|
|
|
|
|
</ol>
|
|
|
|
|
|
|
|
|
|
<p>If you get some free time, and you haven't read them: do so, you might learn
|
2004-12-04 08:32:12 +08:00
|
|
|
something.</p>
|
2003-10-25 01:57:33 +08:00
|
|
|
|
|
|
|
|
</div>
|
2001-07-09 11:27:08 +08:00
|
|
|
|
|
|
|
|
<!-- *********************************************************************** -->
|
|
|
|
|
|
|
|
|
|
<hr>
|
2004-05-13 02:37:22 +08:00
|
|
|
<address>
|
|
|
|
|
<a href="http://jigsaw.w3.org/css-validator/check/referer"><img
|
|
|
|
|
src="http://jigsaw.w3.org/css-validator/images/vcss" alt="Valid CSS!"></a>
|
|
|
|
|
<a href="http://validator.w3.org/check/referer"><img
|
|
|
|
|
src="http://www.w3.org/Icons/valid-html401" alt="Valid HTML 4.01!"></a>
|
|
|
|
|
|
|
|
|
|
<a href="mailto:sabre@nondot.org">Chris Lattner</a><br>
|
2006-03-14 13:39:39 +08:00
|
|
|
<a href="http://llvm.org">LLVM Compiler Infrastructure</a><br>
|
2003-10-25 01:57:33 +08:00
|
|
|
Last modified: $Date$
|
2004-05-13 02:37:22 +08:00
|
|
|
</address>
|
2003-10-25 01:57:33 +08:00
|
|
|
|
|
|
|
|
</body>
|
|
|
|
|
</html>
|
