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
absolute requirements to be followed in all instances, coding standards are
particularly important for large-scale code bases that follow a library-based
design (like LLVM).

While this document may provide guidance for some mechanical formatting issues,
whitespace, or other “microscopic details”, these are not fixed standards.
Always follow the golden rule:

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.

Note that some code bases (e.g. libc++) have really good reasons to deviate
from the coding standards. In the case of libc++, this is because the
naming and other conventions are dictated by the C++ standard. If you think
there is a specific good reason to deviate from the standards here, please bring
it up on the LLVM-dev mailing list.

There are some conventions that are not uniformly followed in the code base
(e.g. the naming convention). This is because they are relatively new, and a
lot of code was written before they were put in place. Our long term goal is
for the entire codebase to follow the convention, but we explicitly do not
want patches that do large-scale reformatting of existing code. On the other
hand, it is reasonable to rename the methods of a class if you’re about to
change it in some other way. Just do the reformatting as a separate commit
from the functionality change.

The ultimate goal of these guidelines is to increase the readability and
maintainability of our common source base. If you have suggestions for topics to
be included, please mail them to Chris.

Most source code in LLVM and other LLVM projects using these coding standards
is C++ code. There are some places where C code is used either due to
environment restrictions, historical restrictions, or due to third-party source
code imported into the tree. Generally, our preference is for standards
conforming, modern, and portable C++ code as the implementation language of
choice.

LLVM, Clang, and LLD are currently written using C++11 conforming code,
although we restrict ourselves to features which are available in the major
toolchains supported as host compilers. The LLDB project is even more
aggressive in the set of host compilers supported and thus uses still more
features. Regardless of the supported features, code is expected to (when
reasonable) be standard, portable, and modern C++11 code. We avoid unnecessary
vendor-specific extensions, etc.

Use the C++ standard library facilities whenever they are available for
a particular task. LLVM and related projects emphasize and rely on the standard
library facilities for as much as possible. Common support libraries providing
functionality missing from the standard library for which there are standard
interfaces or active work on adding standard interfaces will often be
implemented in the LLVM namespace following the expected standard interface.

There are some exceptions such as the standard I/O streams library which are
avoided. Also, there is much more detailed information on these subjects in the
LLVM Programmer’s Manual.

While LLVM, Clang, and LLD use C++11, not all features are available in all of
the toolchains which we support. The set of features supported for use in LLVM
is the intersection of those supported in the minimum requirements described
in the Getting Started with the LLVM System page, section Software.
The ultimate definition of this set is what build bots with those respective
toolchains accept. Don’t argue with the build bots. However, we have some
guidance below to help you know what to expect.

Feel free to use these wherever they make sense and where the =
syntax is allowed. Don’t use braced initialization syntax.

The supported features in the C++11 standard libraries are less well tracked,
but also much greater. Most of the standard libraries implement most of C++11’s
library. The most likely lowest common denominator is Linux support. For
libc++, the support is just poorly tested and undocumented but expected to be
largely complete. YMMV. For libstdc++, the support is documented in detail in
the libstdc++ manual. There are some very minor missing facilities that are
unlikely to be common problems, and there are a few larger gaps that are worth
being aware of:

Not all of the type traits are implemented

No regular expression library.

While most of the atomics library is well implemented, the fences are
missing. Fortunately, they are rarely needed.

The locale support is incomplete.

Other than these areas you should assume the standard library is available and
working as expected until some build bot tells you otherwise. If you’re in an
uncertain area of one of the above points, but you cannot test on a Linux
system, your best approach is to minimize your use of these features, and watch
the Linux build bots to find out if your usage triggered a bug. For example, if
you hit a type trait which doesn’t work we can then add support to LLVM’s
traits header to emulate it.

Comments are one critical part of readability and maintainability. Everyone
knows they should comment their code, and so should you. When writing comments,
write them as English prose, which means they should use proper capitalization,
punctuation, etc. Aim to describe what the code is trying to do and why, not
how it does it at a micro level. Here are a few critical things to document:

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 the
tree. The standard header looks like this:

//===-- llvm/Instruction.h - Instruction class definition -------*- C++ -*-===////// The LLVM Compiler Infrastructure//// This file is distributed under the University of Illinois Open Source// License. See LICENSE.TXT for details.////===----------------------------------------------------------------------===//////// \file/// This file contains the declaration of the Instruction class, which is the/// base class for all of the VM instructions./////===----------------------------------------------------------------------===//

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

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.

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.

The main body is a doxygen comment (identified by the /// comment
marker instead of the usual //) describing the purpose of the file. The
first sentence (or a passage beginning with \brief) is used as an abstract.
Any additional information should be separated by a blank line. If an
algorithm is being implemented or something tricky is going on, a reference
to the paper where it is published should be included, as well as any notes or
gotchas in the code to watch out for.

Classes are one fundamental part of a good object oriented design. As such, a
class definition should have a comment block that explains what the class is
used for and how it works. Every non-trivial class is expected to have a
doxygen comment block.

Methods defined in a class (as well as any global functions) should also be
documented properly. A quick note about what it does and a description of the
borderline behaviour is all that is necessary here (unless something
particularly tricky or insidious is going on). The hope is that people can
figure out how to use your interfaces without reading the code itself.

Good things to talk about here are what happens when something unexpected
happens: does the method return null? Abort? Format your hard disk?

In general, prefer C++ style comments (// for normal comments, /// for
doxygen documentation comments). They take less space, require
less typing, don’t have nesting problems, etc. There are a few cases when it is
useful to use C style (/**/) comments however:

When writing C code: Obviously if you are writing C code, use C style
comments.

When writing a header file that may be #included by a C source file.

When writing a source file that is used by a tool that only accepts C style
comments.

Commenting out large blocks of code is discouraged, but if you really have to do
this (for documentation purposes or as a suggestion for debug printing), use
#if0 and #endif. These nest properly and are better behaved in general
than C style comments.

Use the \file command to turn the standard file header into a file-level
comment.

Include descriptive paragraphs for all public interfaces (public classes,
member and non-member functions). Don’t just restate the information that can
be inferred from the API name. The first sentence (or a paragraph beginning
with \brief) is used as an abstract. Try to use a single sentence as the
\brief adds visual clutter. Put detailed discussion into separate
paragraphs.

To refer to parameter names inside a paragraph, use the \pname command.
Don’t use the \argname command since it starts a new paragraph that
contains documentation for the parameter.

Wrap non-inline code examples in \code...\endcode.

To document a function parameter, start a new paragraph with the
\paramname command. If the parameter is used as an out or an in/out
parameter, use the \param[out]name or \param[in,out]name command,
respectively.

To describe function return value, start a new paragraph with the \returns
command.

A minimal documentation comment:

/// Sets the xyzzy property to \p Baz.voidsetXyzzy(boolBaz);

A documentation comment that uses all Doxygen features in a preferred way:

/// Does foo and bar.////// Does not do foo the usual way if \p Baz is true.////// Typical usage:/// \code/// fooBar(false, "quux", Res);/// \endcode////// \param Quux kind of foo to do./// \param [out] Result filled with bar sequence on foo success.////// \returns true on success.boolfooBar(boolBaz,StringRefQuux,std::vector<int>&Result);

Don’t duplicate the documentation comment in the header file and in the
implementation file. Put the documentation comments for public APIs into the
header file. Documentation comments for private APIs can go to the
implementation file. In any case, implementation files can include additional
comments (not necessarily in Doxygen markup) to explain implementation details
as needed.

Don’t duplicate function or class name at the beginning of the comment.
For humans it is obvious which function or class is being documented;
automatic documentation processing tools are smart enough to bind the comment
to the correct declaration.

Wrong:

// In Something.h:/// Something - An abstraction for some complicated thing.classSomething{public:/// fooBar - Does foo and bar.voidfooBar();};// In Something.cpp:/// fooBar - Does foo and bar.voidSomething::fooBar(){...}

Correct:

// In Something.h:/// An abstraction for some complicated thing.classSomething{public:/// Does foo and bar.voidfooBar();};// In Something.cpp:// Builds a B-tree in order to do foo. See paper by...voidSomething::fooBar(){...}

It is not required to use additional Doxygen features, but sometimes it might
be a good idea to do so.

Consider:

adding comments to any narrow namespace containing a collection of
related functions or types;

using top-level groups to organize a collection of related functions at
namespace scope where the grouping is smaller than the namespace;

using member groups and additional comments attached to member
groups to organize within a class.

and each category should be sorted lexicographically by the full path.

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 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.

LLVM project and subproject headers should be grouped from most specific to least
specific, for the same reasons described above. For example, LLDB depends on
both clang and LLVM, and clang depends on LLVM. So an LLDB source file should
include lldb headers first, followed by clang headers, followed by
llvm headers, to reduce the possibility (for example) of an LLDB header
accidentally picking up a missing include due to the previous inclusion of that
header in the main source file or some earlier header file. clang should
similarly include its own headers before including llvm headers. This rule
applies to all LLVM subprojects.

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.

The longer answer is that there must be some limit to the width of the code in
order to reasonably allow developers to have multiple files side-by-side in
windows on a modest display. If you are going to pick a width limit, it is
somewhat arbitrary but you might as well pick something standard. Going with 90
columns (for example) instead of 80 columns wouldn’t add any significant value
and would be detrimental to printing out code. Also many other projects have
standardized on 80 columns, so some people have already configured their editors
for it (vs something else, like 90 columns).

This is one of many contentious issues in coding standards, but it is not up for
debate.

In all cases, prefer spaces to tabs in source files. People have different
preferred indentation levels, and different styles of indentation that they
like; this is fine. What isn’t fine is that different editors/viewers expand
tabs out to different tab stops. This can cause your code to look completely
unreadable, and it is not worth dealing with.

As always, follow the Golden Rule above: follow the style of
existing code if you are modifying and extending it. If you like four spaces of
indentation, DO NOT do that in the middle of a chunk of code with two spaces
of indentation. Also, do not reindent a whole source file: it makes for
incredible diffs that are absolutely worthless.

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. With the introduction of C++11, there are some new formatting
challenges that merit some suggestions to help have consistent, maintainable,
and tool-friendly formatting and indentation.

When formatting a multi-line lambda, format it like a block of code, that’s
what it is. If there is only one multi-line lambda in a statement, and there
are no expressions lexically after it in the statement, drop the indent to the
standard two space indent for a block of code, as if it were an if-block opened
by the preceding part of the statement:

To take best advantage of this formatting, if you are designing an API which
accepts a continuation or single callable argument (be it a functor, or
a std::function), it should be the last argument if at all possible.

If there are multiple multi-line lambdas in a statement, or there is anything
interesting after the lambda in the statement, indent the block two spaces from
the indent of the []:

With C++11, there are significantly more uses of braced lists to perform
initialization. These allow you to easily construct aggregate temporaries in
expressions among other niceness. They now have a natural way of ending up
nested within each other and within function calls in order to build up
aggregates (such as option structs) from local variables. To make matters
worse, we also have many more uses of braces in an expression context that are
not performing initialization.

The historically common formatting of braced initialization of aggregate
variables does not mix cleanly with deep nesting, general expression contexts,
function arguments, and lambdas. We suggest new code use a simple rule for
formatting braced initialization lists: act as-if the braces were parentheses
in a function call. The formatting rules exactly match those already well
understood for formatting nested function calls. Examples:

If your code has compiler warnings in it, something is wrong — you aren’t
casting values correctly, you 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.

It is not possible to prevent all warnings from all compilers, nor is it
desirable. Instead, pick a standard compiler (like gcc) that provides a
good thorough set of warnings, and stick to it. At least in the case of
gcc, it is possible to work around any spurious errors by changing the
syntax of the code slightly. For example, a warning that annoys me occurs when
I write code like this:

if(V=getValue()){...}

gcc will warn me that I probably want to use the == 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:

if((V=getValue())){...}

which shuts gcc up. Any gcc warning that annoys you can be fixed by
massaging the code appropriately.

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.

In practice, this means that you shouldn’t assume much about the host compiler
(and Visual Studio tends to be the lowest common denominator). If advanced
features are used, they should only be an implementation detail of a library
which has a simple exposed API, and preferably be buried in libSystem.

In an effort to reduce code and executable size, LLVM does not use RTTI
(e.g. dynamic_cast<>;) or exceptions. These two language features violate
the general C++ principle of “you only pay for what you use”, causing
executable bloat even if exceptions are never used in the code base, or if RTTI
is never used for a class. Because of this, we turn them off globally in the
code.

That said, LLVM does make extensive use of a hand-rolled form of RTTI that use
templates like isa<>, cast<>, and dyn_cast<>.
This form of RTTI is opt-in and can be
added to any class. It is also
substantially more efficient than dynamic_cast<>.

Static constructors and destructors (e.g. global variables whose types have a
constructor or destructor) should not be added to the code base, and should be
removed wherever possible. Besides well known problems where the order of
initialization is undefined between globals in different source files, the
entire concept of static constructors is at odds with the common use case of
LLVM as a library linked into a larger application.

Consider the use of LLVM as a JIT linked into another application (perhaps for
OpenGL, custom languages, shaders in movies, etc). Due to the
design of static constructors, they must be executed at startup time of the
entire application, regardless of whether or how LLVM is used in that larger
application. There are two problems with this:

The time to run the static constructors impacts startup time of applications
— a critical time for GUI apps, among others.

The static constructors cause the app to pull many extra pages of memory off
the disk: both the code for the constructor 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.

We would really like for there to be zero cost for linking in an additional LLVM
target or other library into an application, but static constructors violate
this goal.

That said, LLVM unfortunately does contain static constructors. It would be a
great project for someone to purge all static
constructors from LLVM, and then enable the -Wglobal-constructors warning
flag (when building with Clang) to ensure we do not regress in the future.

In C++, the class and struct keywords can be used almost
interchangeably. The only difference is when they are used to declare a class:
class makes all members private by default while struct makes all
members public by default.

Unfortunately, not all compilers follow the rules and some will generate
different symbols based on whether class or struct was used to declare
the symbol (e.g., MSVC). This can lead to problems at link time.

All declarations and definitions of a given class or struct must use
the same keyword. For example:

classFoo;// Breaks mangling in MSVC.structFoo{intData;};

As a rule of thumb, struct should be kept to structures where all
members are declared public.

// Foo feels like a class... this is strange.structFoo{private:intData;public:Foo():Data(0){}intgetData()const{returnData;}voidsetData(intD){Data=D;}};// Bar isn't POD, but it does look like a struct.structBar{intData;Bar():Data(0){}};

In C++11 there is a “generalized initialization syntax” which allows calling
constructors using braced initializer lists. Do not use these to call
constructors with any interesting logic or if you care that you’re calling some
particular constructor. Those should look like function calls using
parentheses rather than like aggregate initialization. Similarly, if you need
to explicitly name the type and call its constructor to create a temporary,
don’t use a braced initializer list. Instead, use a braced initializer list
(without any type for temporaries) when doing aggregate initialization or
something notionally equivalent. Examples:

classFoo{public:// Construct a Foo by reading data from the disk in the whizbang format, ...Foo(std::stringfilename);// Construct a Foo by looking up the Nth element of some global data ...Foo(intN);// ...};// The Foo constructor call is very deliberate, no braces.std::fill(foo.begin(),foo.end(),Foo("name"));// The pair is just being constructed like an aggregate, use braces.bar_map.insert({my_key,my_value});

If you use a braced initializer list when initializing a variable, use an equals before the open curly brace:

Some are advocating a policy of “almost always auto” in C++11, however LLVM
uses a more moderate stance. Use auto if and only if it makes the code more
readable or easier to maintain. Don’t “almost always” use auto, but do use
auto with initializers like cast<Foo>(...) or other places where the
type is already obvious from the context. Another time when auto works well
for these purposes is when the type would have been abstracted away anyways,
often behind a container’s typedef such as std::vector<T>::iterator.

The convenience of auto makes it easy to forget that its default behavior
is a copy. Particularly in range-based for loops, careless copies are
expensive.

As a rule of thumb, use auto& unless you need to copy the result, and use
auto* when copying pointers.

// Typically there's no reason to copy.for(constauto&Val:Container){observe(Val);}for(auto&Val:Container){Val.change();}// Remove the reference if you really want a new copy.for(autoVal:Container){Val.change();saveSomewhere(Val);}// Copy pointers, but make it clear that they're pointers.for(constauto*Ptr:Container){observe(*Ptr);}for(auto*Ptr:Container){Ptr->change();}

In general, there is no relative ordering among pointers. As a result,
when unordered containers like sets and maps are used with pointer keys
the iteration order is undefined. Hence, iterating such containers may
result in non-deterministic code generation. While the generated code
might not necessarily be “wrong code”, this non-determinism might result
in unexpected runtime crashes or simply hard to reproduce bugs on the
customer side making it harder to debug and fix.

As a rule of thumb, in case an ordered result is expected, remember to
sort an unordered container before iteration. Or use ordered containers
like vector/MapVector/SetVector if you want to iterate pointer keys.

std::sort uses a non-stable sorting algorithm in which the order of equal
elements is not guaranteed to be preserved. Thus using std::sort for a
container having equal elements may result in non-determinstic behavior.
To uncover such instances of non-determinism, LLVM has introduced a new
llvm::sort wrapper function. For an EXPENSIVE_CHECKS build this will randomly
shuffle the container before sorting. As a rule of thumb, always make sure to
use llvm::sort instead of std::sort.

Header files should be self-contained (compile on their own) and end in .h.
Non-header files that are meant for inclusion should end in .inc and be used
sparingly.

All header files should be self-contained. Users and refactoring tools should
not have to adhere to special conditions to include the header. Specifically, a
header should have header guards and include all other headers it needs.

There are rare cases where a file designed to be included is not
self-contained. These are typically intended to be included at unusual
locations, such as the middle of another file. They might not use header
guards, and might not include their prerequisites. Name such files with the
.inc extension. Use sparingly, and prefer self-contained headers when possible.

In general, a header should be implemented by one or more .cpp files. Each
of these .cpp files should include the header that defines their interface
first. This ensures that all of the dependences of the header have been
properly added to the header itself, and are not implicit. System headers
should be included after user headers for a translation unit.

A directory of header files (for example include/llvm/Foo) defines a
library (Foo). Dependencies between libraries are defined by the
LLVMBuild.txt file in their implementation (lib/Foo). One library (both
its headers and implementation) should only use things from the libraries
listed in its dependencies.

Some of this constraint can be enforced by classic Unix linkers (Mac & Windows
linkers, as well as lld, do not enforce this constraint). A Unix linker
searches left to right through the libraries specified on its command line and
never revisits a library. In this way, no circular dependencies between
libraries can exist.

This doesn’t fully enforce all inter-library dependencies, and importantly
doesn’t enforce header file circular dependencies created by inline functions.
A good way to answer the “is this layered correctly” would be to consider
whether a Unix linker would succeed at linking the program if all inline
functions were defined out-of-line. (& for all valid orderings of dependencies
- since linking resolution is linear, it’s possible that some implicit
dependencies can sneak through: A depends on B and C, so valid orderings are
“C B A” or “B C A”, in both cases the explicit dependencies come before their
use. But in the first case, B could still link successfully if it implicitly
depended on C, or the opposite in the second case)

#include hurts compile time performance. Don’t do it unless you have to,
especially in header files.

But wait! Sometimes you need to have the definition of a class to use it, or to
inherit from it. In these cases go ahead and #include 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 #includeing speeds up
compilation.

It is easy to try to go too overboard on this recommendation, however. You
must include all of the header files that you are using — you can include
them either directly or indirectly through another header file. To make sure
that you don’t accidentally forget to include a header file in your module
header, make sure to include your module header first in the implementation
file (as mentioned above). This way there won’t be any hidden dependencies that
you’ll find out about later.

Many modules have a complex implementation that causes them to use more than one
implementation (.cpp) file. It is often tempting to put the internal
communication interface (helper classes, extra functions, etc) in the public
module header file. Don’t do this!

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.

Note

It’s okay to put extra implementation methods in a public class itself. Just
make them private (or protected) and all is well.

When reading code, keep in mind how much state and how many previous decisions
have to be remembered by the reader to understand a block of code. Aim to
reduce indentation where possible when it doesn’t make it more difficult to
understand the code. One great way to do this is by making use of early exits
and the continue keyword in long loops. As an example of using an early
exit from a function, consider this “bad” code:

This code has several problems if the body of the 'if' is large. When
you’re looking at the top of the function, it isn’t immediately clear that this
only does interesting things with non-terminator instructions, and only
applies to things with the other predicates. Second, it is relatively difficult
to describe (in comments) why these predicates are important because the if
statement makes it difficult to lay out the comments. Third, when you’re deep
within the body of the code, it is indented an extra level. Finally, when
reading the top of the function, it isn’t clear what the result is if the
predicate isn’t true; you have to read to the end of the function to know that
it returns null.

It is much preferred to format the code like this:

Value*doSomething(Instruction*I){// Terminators never need 'something' done to them because ...if(isa<TerminatorInst>(I))return0;// We conservatively avoid transforming instructions with multiple uses// because goats like cheese.if(!I->hasOneUse())return0;// This is really just here for example.if(!doOtherThing(I))return0;...somelongcode....}

This fixes these problems. A similar problem frequently happens in for
loops. A silly example is something like this:

When you have very, very small loops, this sort of structure is fine. But if it
exceeds more than 10-15 lines, it becomes difficult for people to read and
understand at a glance. The problem with this sort of code is that it gets very
nested very quickly. Meaning that the reader of the code has to keep a lot of
context in their brain to remember what is going immediately on in the loop,
because they don’t know if/when the if conditions will have elses etc.
It is strongly preferred to structure the loop like this:

This has all the benefits of using early exits for functions: it reduces nesting
of the loop, it makes it easier to describe why the conditions are true, and it
makes it obvious to the reader that there is no else coming up that they
have to push context into their brain for. If a loop is large, this can be a
big understandability win.

For similar reasons above (reduction of indentation and easier reading), please
do not use 'else' or 'elseif' after something that interrupts control
flow — like return, break, continue, goto, etc. For
example, this is bad:

This sort of code is awkward to write, and is almost always a bad sign. Instead
of this sort of loop, we strongly prefer to use a predicate function (which may
be static) that uses early exits to compute the predicate. We prefer the
code to be structured like this:

/// \returns true if the specified list has an element that is a foo.staticboolcontainsFoo(conststd::vector<Bar*>&List){for(unsignedI=0,E=List.size();I!=E;++I)if(List[I]->isFoo())returntrue;returnfalse;}...if(containsFoo(BarList)){...}

There are many reasons for doing this: it reduces indentation and factors out
code which can often be shared by other code that checks for the same predicate.
More importantly, it forces you to pick a name for the function, and forces
you to write a comment for it. In this silly example, this doesn’t add much
value. However, if the condition is complex, this can make it a lot easier for
the reader to understand the code that queries for this predicate. Instead of
being faced with the in-line details of how we check to see if the BarList
contains a foo, we can trust the function name and continue reading with better
locality.

Poorly-chosen names can mislead the reader and cause bugs. We cannot stress
enough how important it is to use descriptive names. Pick names that match
the semantics and role of the underlying entities, within reason. Avoid
abbreviations unless they are well known. After picking a good name, make sure
to use consistent capitalization for the name, as inconsistency requires clients
to either memorize the APIs or to look it up to find the exact spelling.

In general, names should be in camel case (e.g. TextFileReader and
isLValue()). Different kinds of declarations have different rules:

Variable names should be nouns (as they represent state). The name should
be camel case, and start with an upper case letter (e.g. Leader or
Boats).

Function names should be verb phrases (as they represent actions), and
command-like function should be imperative. The name should be camel case,
and start with a lower case letter (e.g. openFile() or isFoo()).

Enum declarations (e.g. enumFoo{...}) are types, so they should
follow the naming conventions for types. A common use for enums is as a
discriminator for a union, or an indicator of a subclass. When an enum is
used for something like this, it should have a Kind suffix
(e.g. ValueKind).

Enumerators (e.g. enum{Foo,Bar}) and public member variables
should start with an upper-case letter, just like types. Unless the
enumerators are defined in their own small namespace or inside a class,
enumerators should have a prefix corresponding to the enum declaration name.
For example, enumValueKind{...}; may contain enumerators like
VK_Argument, VK_BasicBlock, etc. Enumerators that are just
convenience constants are exempt from the requirement for a prefix. For
instance:

enum{MaxSize=42,Density=12};

As an exception, classes that mimic STL classes can have member names in STL’s
style of lower-case words separated by underscores (e.g. begin(),
push_back(), and empty()). Classes that provide multiple
iterators should add a singular prefix to begin() and end()
(e.g. global_begin() and use_begin()).

Here are some examples of good and bad names:

classVehicleMaker{...Factory<Tire>F;// Bad -- abbreviation and non-descriptive.Factory<Tire>Factory;// Better.Factory<Tire>TireFactory;// Even better -- if VehicleMaker has more than one// kind of factories.};VehiclemakeVehicle(VehicleTypeType){VehicleMakerM;// Might be OK if having a short life-span.TireTmp1=M.makeTire();// Bad -- 'Tmp1' provides no information.LightHeadlight=M.makeLight("head");// Good -- descriptive....}

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 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 debugger make sense of why an assertion is being made and
enforced, and hopefully what to do about it. Here is one complete example:

inlineValue*getOperand(unsignedI){assert(I<Operands.size()&&"getOperand() out of range!");returnOperands[I];}

Here are more examples:

assert(Ty->isPointerType()&&"Can't allocate a non-pointer type!");assert((Opcode==Shl||Opcode==Shr)&&"ShiftInst Opcode invalid!");assert(idx<getNumSuccessors()&&"Successor # out of range!");assert(V1.getType()==V2.getType()&&"Constant types must be identical!");assert(isa<PHINode>(Succ->front())&&"Only works on PHId BBs!");

You get the idea.

In the past, asserts were used to indicate a piece of code that should not be
reached. These were typically of the form:

assert(0&&"Invalid radix for integer literal");

This has a few issues, the main one being that some compilers might not
understand the assertion, or warn about a missing return in builds where
assertions are compiled out.

Today, we have something much better: llvm_unreachable:

llvm_unreachable("Invalid radix for integer literal");

When assertions are enabled, this will print the message if it’s ever reached
and then exit the program. When assertions are disabled (i.e. in release
builds), llvm_unreachable becomes a hint to compilers to skip generating
code for this branch. If the compiler does not support this, it will fall back
to the “abort” implementation.

Neither assertions or llvm_unreachable will abort the program on a release
build. If the error condition can be triggered by user input then the
recoverable error mechanism described in LLVM Programmer’s Manual should be
used instead. In cases where this is not practical, report_fatal_error may
be used.

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:

unsignedSize=V.size();assert(Size>42&&"Vector smaller than it should be");boolNewToSet=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");boolNewToSet=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 “usingnamespacestd;”.

In header files, adding a 'usingnamespaceXXX' 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 'usingnamespacestd;' 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 'usingnamespacellvm;' directive at the 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 vtable (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.

-Wswitch warns if a switch, without a default label, over an enumeration
does not cover every enumeration value. If you write a default label on a fully
covered switch over an enumeration then the -Wswitch warning won’t fire
when new elements are added to that enumeration. To help avoid adding these
kinds of defaults, Clang has the warning -Wcovered-switch-default which is
off by default but turned on when building LLVM with a version of Clang that
supports the warning.

A knock-on effect of this stylistic requirement is that when building LLVM with
GCC you may get warnings related to “control may reach end of non-void function”
if you return from each case of a covered switch-over-enum because GCC assumes
that the enum expression may take any representable value, not just those of
individual enumerators. To suppress this warning, use llvm_unreachable after
the switch.

The introduction of range-based for loops in C++11 means that explicit
manipulation of iterators is rarely necessary. We use range-based for
loops wherever possible for all newly added code. For example:

In cases where range-based for loops can’t be used and it is necessary
to write an explicit iterator-based loop, pay close attention to whether
end() is re-evaluted on each loop iteration. One common mistake is to
write a loop in this style:

BasicBlock*BB=...for(autoI=BB->begin();I!=BB->end();++I)...useI...

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:

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,
because many common implementations transparently inject a static constructor
into every translation unit that includes it.

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.

Note

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 classraw_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'.

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:

if(X)...for(I=0;I!=100;++I)...while(LLVMRocks)...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(LLVMRocks)...somefunc(42);assert(3!=4&&"laws of math are failing me");A=foo(42,92)+bar(X);

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.

Hard fast rule: Preincrement (++X) may be no slower than postincrement
(X++) and could very well be a lot faster than it. Use preincrementation
whenever possible.

The semantics of postincrement include making a copy of the value being
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,
get in the habit of always using preincrement, and you won’t have a problem.

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. To facilitate this and
avoid some insanely deep nesting on occasion, don’t indent namespaces. If it
helps readability, feel free to add a comment indicating what namespace is
being closed by a }. For example:

namespacellvm{namespaceknowledge{/// This class represents things that Smith can have an intimate/// understanding of and contains the data associated with it.classGrokable{...public:explicitGrokable(){...}virtual~Grokable()=0;...};}// end namespace knowledge}// end namespace llvm

Feel free to skip the closing comment when the namespace being closed is
obvious for any reason. For example, the outer-most namespace in a header file
is rarely a source of confusion. But namespaces both anonymous and named in
source files that are being closed half way through the file probably could use
clarification.

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:

This is bad specifically because if you’re looking at “runHelper” 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.