Use the "assert" function to its fullest. Check all of your -preconditions and assumptions, you never know when a bug (not neccesarily even +
Use the "assert" macro to its fullest. Check all of your +preconditions and assumptions, you never know when a bug (not necessarily even yours) might be caught early by an assertion, which reduces debugging time dramatically. The "<cassert>" header file is probably already included by the header files you are using, so it doesn't cost anything to use @@ -503,7 +800,7 @@ it.
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 -helps the poor debugging make sense of why an assertion is being made and +helps the poor debugger make sense of why an assertion is being made and enforced, and hopefully what to do about it. Here is one complete example:
You get the idea...
+Please be aware when adding assert statements that not all compilers are aware of +the semantics of the assert. In some places, asserts are used to indicate a piece of +code that should not be reached. These are typically of the form:
+ ++assert(0 && "Some helpful error message"); ++
When used in a function that returns a value, they should be followed with a return +statement and a comment indicating that this line is never reached. This will prevent +a compiler which is unable to deduce that the assert statement never returns from +generating a warning.
+ ++assert(0 && "Some helpful error message"); +// Not reached +return 0; ++
Another issue is that values used only by assertions will produce an "unused + value" warning when assertions are disabled. For example, this code will warn: +
+ ++ unsigned Size = V.size(); + assert(Size > 42 && "Vector smaller than it should be"); + + bool NewToSet = Myset.insert(Value); + assert(NewToSet && "The value shouldn't be in the set yet"); ++
These are two interesting different cases: in the first case, the call to +V.size() is only useful for the assert, and we don't want it executed when +assertions are disabled. Code like this should move the call into the assert +itself. In the second case, the side effects of the call must happen whether +the assert is enabled or not. In this case, the value should be cast to void +to disable the warning. To be specific, it is preferred to write the code +like this:
+ ++ assert(V.size() > 42 && "Vector smaller than it should be"); + + bool NewToSet = Myset.insert(Value); (void)NewToSet; + assert(NewToSet && "The value shouldn't be in the set yet"); ++
In LLVM, we prefer to explicitly prefix all identifiers from the standard -namespace with an "std::" prefix, rather than rely on "using namespace std;". -
+namespace with an "std::" prefix, rather than rely on +"using namespace std;". + +In header files, adding a 'using namespace XXX' directive pollutes +the namespace of any source file that #includes the header. This is +clearly a bad thing.
+ +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 clearer, because it is immediately obvious what facilities +are being used and where they are coming from, and more portable, 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 std namespace. As +such, we never use 'using namespace std;' in LLVM.
+ +The exception to the general rule (i.e. it's not an exception for +the std 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 +'using namespace llvm' directive at their top, after the +#includes. This reduces indentation in the body of the file for source +editors that indent based on braces, and keeps the conceptual context cleaner. +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.
+ +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.
+ +Because C++ doesn't have a standard "foreach" loop (though it can be emulated +with macros and may be coming in C++'0x) we end up writing a lot of loops that +manually iterate from begin to end on a variety of containers or through other +data structures. One common mistake is to write a loop in this style:
+ ++ BasicBlock *BB = ... + for (BasicBlock::iterator I = BB->begin(); I != BB->end(); ++I) + ... use I ... ++
The problem with this construct is that it evaluates "BB->end()" +every time through the loop. Instead of writing the loop like this, we strongly +prefer loops to be written so that they evaluate it once before the loop starts. +A convenient way to do this is like so:
+ ++ BasicBlock *BB = ... + for (BasicBlock::iterator I = BB->begin(), E = BB->end(); I != E; ++I) + ... use I ... ++
The observant may quickly point out that these two loops may have different +semantics: if the container (a basic block in this case) is being mutated, then +"BB->end()" may change its value every time through the loop and the +second loop may not in fact be correct. If you actually do depend on this +behavior, please write the loop in the first form and add a comment indicating +that you did it intentionally.
+ +Why do we prefer the second form (when correct)? Writing the loop in the +first form has two problems: First it may be less efficient than evaluating it +at the start of the loop. In this case, the cost is probably minor: a few extra +loads every time through the loop. However, if the base expression is more +complex, then the cost can rise quickly. I've seen loops where the end +expression was actually something like: "SomeMap[x]->end()" and map +lookups really aren't cheap. By writing it in the second form consistently, you +eliminate the issue entirely and don't even have to think about it.
+ +The second (even bigger) issue is that writing the loop in the first form +hints to the reader that the loop is mutating the container (a fact that a +comment would handily confirm!). If you write the loop in the second form, it +is immediately obvious without even looking at the body of the loop that the +container isn't being modified, which makes it easier to read the code and +understand what it does.
+ +While the second form of the loop is a few extra keystrokes, we do strongly +prefer it.
+ +The use of #include <iostream> in library files is +hereby forbidden. 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:
+ +-
+
- The time to run the static c'tors impacts startup time of + applications—a critical time for GUI apps. +
- The static c'tors cause the app to pull many extra pages of memory off the + disk: both the code for the static c'tors in each .o 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. +
Note that using the other stream headers (<sstream> for +example) is not problematic in this regard (just <iostream>). +However, raw_ostream provides various APIs that are better performing for almost +every use than std::ostream style APIs. +Therefore new code should always +use raw_ostream for writing, or +the llvm::MemoryBuffer API for reading files.
+ +LLVM includes a lightweight, simple, and efficient stream implementation +in llvm/Support/raw_ostream.h which provides all of the common features +of std::ostream. All new code should use raw_ostream instead +of ostream.
+ +Unlike std::ostream, raw_ostream is not a template and can +be forward declared as class raw_ostream. Public headers should +generally not include the raw_ostream header, but use forward +declarations and constant references to raw_ostream instances.
+ +The std::endl 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:
+ ++std::cout << std::endl; +std::cout << '\n' << std::flush; ++
Most of the time, you probably have no reason to flush the output stream, so +it's better to use a literal '\n'.
+ +This section describes preferred low-level formatting guidelines along with +reasoning on why we prefer them.
+ + + + +In header files, adding a 'using namespace XXX' directive pollutes the -namespace of any source file that includes the header. This is clearly a bad -thing.
+We prefer to put a space before an open parenthesis only in control flow +statements, but not in normal function call expressions and function-like +macros. For example, this is good:
-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 more clear - because it is immediately obvious what facilities -are being used and where they are coming from - and more portable - -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 std -namespace. As such, we never 'using namespace std;' in LLVM.
++ if (x) ... + for (i = 0; i != 100; ++i) ... + while (llvm_rocks) ... + + somefunc(42); + assert(3 != 4 && "laws of math are failing me"); + + a = foo(42, 92) + bar(x); ++
... and this is bad:
+ ++ if(x) ... + for(i = 0; i != 100; ++i) ... + while(llvm_rocks) ... + + somefunc (42); + assert (3 != 4 && "laws of math are failing me"); + + a = foo (42, 92) + bar (x); ++
The exception to the general rule (i.e. it's not an exception for the std -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 more clear, for the .cpp files to have a 'using namespace -llvm' directive at their top, after the #includes. 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.
+The reason for doing this is not completely arbitrary. This style makes + control flow operators stand out more, and makes expressions flow better. The + function call operator binds very tightly as a postfix operator. Putting + a space after a function name (as in the last example) makes it appear that + the code might bind the arguments of the left-hand-side of a binary operator + with the argument list of a function and the name of the right side. More + specifically, it is easy to misread the "a" example as:
+ ++ a = foo ((42, 92) + bar) (x); ++
... when skimming through the code. By avoiding a space in a function, we +avoid this misinterpretation.
The std::endl 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:
++In general, we strive to reduce indentation wherever possible. This is useful +because we want code to fit into 80 columns without +wrapping horribly, but also because it makes it easier to understand the code. +Namespaces are a funny thing: they are often large, and we often desire to put +lots of stuff into them (so they can be large). Other times they are tiny, +because they just hold an enum or something similar. In order to balance this, +we use different approaches for small versus large namespaces. +
+ ++If a namespace definition is small and easily fits on a screen (say, +less than 35 lines of code), then you should indent its body. Here's an +example: +
-std::cout << std::endl;
-std::cout << '\n' << std::flush;
+namespace llvm {
+ namespace X86 {
+ /// RelocationType - An enum for the x86 relocation codes. Note that
+ /// the terminology here doesn't follow x86 convention - word means
+ /// 32-bit and dword means 64-bit.
+ enum RelocationType {
+ /// reloc_pcrel_word - PC relative relocation, add the relocated value to
+ /// the value already in memory, after we adjust it for where the PC is.
+ reloc_pcrel_word = 0,
+
+ /// reloc_picrel_word - PIC base relative relocation, add the relocated
+ /// value to the value already in memory, after we adjust it for where the
+ /// PIC base is.
+ reloc_picrel_word = 1,
+
+ /// reloc_absolute_word, reloc_absolute_dword - Absolute relocation, just
+ /// add the relocated value to the value already in memory.
+ reloc_absolute_word = 2,
+ reloc_absolute_dword = 3
+ };
+ }
+}
Most of the time, you probably have no reason to flush the output stream, so -it's better to use a literal '\n'.
+Since the body is small, indenting adds value because it makes it very clear +where the namespace starts and ends, and it is easy to take the whole thing in +in one "gulp" when reading the code. If the blob of code in the namespace is +larger (as it typically is in a header in the llvm or clang namespaces), do not +indent the code, and add a comment indicating what namespace is being closed. +For example:
+ +
+namespace llvm {
+namespace knowledge {
+
+/// Grokable - This class represents things that Smith can have an intimate
+/// understanding of and contains the data associated with it.
+class Grokable {
+...
+public:
+ explicit Grokable() { ... }
+ virtual ~Grokable() = 0;
+
+ ...
+
+};
+
+} // end namespace knowledge
+} // end namespace llvm
+
+Because the class is large, we don't expect that the reader can easily +understand the entire concept in a glance, and the end of the file (where the +namespaces end) may be a long ways away from the place they open. As such, +indenting the contents of the namespace doesn't add any value, and detracts from +the readability of the class. In these cases it is best to not indent +the contents of the namespace.
+ +After talking about namespaces in general, you may be wondering about +anonymous namespaces in particular. +Anonymous namespaces are a great language feature that tells the C++ compiler +that the contents of the namespace are only visible within the current +translation unit, allowing more aggressive optimization and eliminating the +possibility of symbol name collisions. Anonymous namespaces are to C++ as +"static" is to C functions and global variables. While "static" is available +in C++, anonymous namespaces are more general: they can make entire classes +private to a file.
+ +The problem with anonymous namespaces is that they naturally want to +encourage indentation of their body, and they reduce locality of reference: if +you see a random function definition in a C++ file, it is easy to see if it is +marked static, but seeing if it is in an anonymous namespace requires scanning +a big chunk of the file.
+ +Because of this, we have a simple guideline: make anonymous namespaces as +small as possible, and only use them for class declarations. For example, this +is good:
+ +
+namespace {
+ class StringSort {
+ ...
+ public:
+ StringSort(...)
+ bool operator<(const char *RHS) const;
+ };
+} // end anonymous namespace
+
+static void Helper() {
+ ...
+}
+
+bool StringSort::operator<(const char *RHS) const {
+ ...
+}
+
+
+This is bad:
+ + +
+namespace {
+class StringSort {
+...
+public:
+ StringSort(...)
+ bool operator<(const char *RHS) const;
+};
+
+void Helper() {
+ ...
+}
+
+bool StringSort::operator<(const char *RHS) const {
+ ...
+}
+
+} // end anonymous namespace
+
+
This is bad specifically because if you're looking at "Helper" in the middle +of a large C++ file, that you have no immediate way to tell if it is local to +the file. When it is marked static explicitly, this is immediately obvious. +Also, there is no reason to enclose the definition of "operator<" in the +namespace just because it was declared there. +
+ +-
-
- Effective -C++ by Scott Meyers. There is an online version of the book (only some -chapters though) available as well. Also +
- Effective +C++ by Scott Meyers. Also interesting and useful are "More Effective C++" and "Effective STL" by the same author. -
- Large-Scale C++ -Software Design by John Lakos +
- Large-Scale C++ Software Design by John Lakos
+ src="http://jigsaw.w3.org/css-validator/images/vcss-blue" alt="Valid CSS">
- LLVM Compiler Infrastructure
+ LLVM Compiler Infrastructure
Last modified: $Date$