A few things to note about this particular format: The "-*- C++ -*-" string on the first line is there to tell Emacs that the source file -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 +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.
@@ -244,7 +244,7 @@ file should be listed. We prefer these #includes to be listed in this order:... and each category should be sorted by name.
-The "Main Module Header" file applies to .cpp file -which implement an interface defined by a .h file. This #include +
The "Main Module Header" file applies to .cpp files +which implement an interface defined by a .h file. This #include should always be included first regardless of where it lives on the file -system. By including a header file first in the .cpp files that implement the +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 +form of documentation in the .cpp file to indicate where the interfaces it implements are defined.
@@ -323,7 +323,7 @@ makes for incredible diffs that are absolutely worthless.Okay, your first year of programming you were told that indentation is +
Okay, in 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.
@@ -434,7 +434,7 @@ declare the symbol. This can lead to problems at link time. @@ -462,7 +462,7 @@ together.In general, a module should be implemented with one or more .cpp files. Each of these .cpp files should include the header that defines -their interface first. This ensure that all of the dependences of the module +their interface first. This ensures 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.
@@ -581,7 +581,7 @@ Value *DoSomething(Instruction *I) {This fixes these problems. A similar problem frequently happens in for +
This fixes these problems. A similar problem frequently happens in for loops. A silly example is something like this:
Use the "assert" function to its fullest. Check all of your +
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 @@ -799,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:
In implementation files (e.g. .cpp files), the rule is more of a stylistic +
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 @@ -913,9 +914,9 @@ 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 +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. The -general form of this rule is that any .cpp file that implements code in any +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.
@@ -1024,17 +1025,35 @@ library. There are two problems with this: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, so you should just use it for new -code.
- -New code should always +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.
+ +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.
- -We prefer to put a space before a parentheses only in control flow +
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:
@@ -1174,7 +1173,7 @@ get in the habit of always using preincrement, and you won't have a problem.-In general, we strive to reduce indentation where ever possible. This is useful +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 @@ -1219,7 +1218,7 @@ namespace llvm {
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 +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: