[ARM] Fixup pipeline test. NFC
[llvm-complete.git] / docs / CodingStandards.rst
blobf1873c92da1468858cf07ad661ebe3df72246dc0
1 =====================
2 LLVM Coding Standards
3 =====================
5 .. contents::
6    :local:
8 Introduction
9 ============
11 This document attempts to describe a few coding standards that are being used in
12 the LLVM source tree.  Although no coding standards should be regarded as
13 absolute requirements to be followed in all instances, coding standards are
14 particularly important for large-scale code bases that follow a library-based
15 design (like LLVM).
17 While this document may provide guidance for some mechanical formatting issues,
18 whitespace, or other "microscopic details", these are not fixed standards.
19 Always follow the golden rule:
21 .. _Golden Rule:
23     **If you are extending, enhancing, or bug fixing already implemented code,
24     use the style that is already being used so that the source is uniform and
25     easy to follow.**
27 Note that some code bases (e.g. ``libc++``) have really good reasons to deviate
28 from the coding standards.  In the case of ``libc++``, this is because the
29 naming and other conventions are dictated by the C++ standard.  If you think
30 there is a specific good reason to deviate from the standards here, please bring
31 it up on the LLVM-dev mailing list.
33 There are some conventions that are not uniformly followed in the code base
34 (e.g. the naming convention).  This is because they are relatively new, and a
35 lot of code was written before they were put in place.  Our long term goal is
36 for the entire codebase to follow the convention, but we explicitly *do not*
37 want patches that do large-scale reformatting of existing code.  On the other
38 hand, it is reasonable to rename the methods of a class if you're about to
39 change it in some other way.  Just do the reformatting as a separate commit
40 from the functionality change.
41   
42 The ultimate goal of these guidelines is to increase the readability and
43 maintainability of our common source base. If you have suggestions for topics to
44 be included, please mail them to `Chris <mailto:sabre@nondot.org>`_.
46 Languages, Libraries, and Standards
47 ===================================
49 Most source code in LLVM and other LLVM projects using these coding standards
50 is C++ code. There are some places where C code is used either due to
51 environment restrictions, historical restrictions, or due to third-party source
52 code imported into the tree. Generally, our preference is for standards
53 conforming, modern, and portable C++ code as the implementation language of
54 choice.
56 C++ Standard Versions
57 ---------------------
59 LLVM, Clang, and LLD are currently written using C++14 conforming code,
60 although we restrict ourselves to features which are available in the major
61 toolchains supported as host compilers. The LLDB project is even more
62 aggressive in the set of host compilers supported and thus uses still more
63 features. Regardless of the supported features, code is expected to (when
64 reasonable) be standard, portable, and modern C++14 code. We avoid unnecessary
65 vendor-specific extensions, etc.
67 C++ Standard Library
68 --------------------
70 Use the C++ standard library facilities whenever they are available for
71 a particular task. LLVM and related projects emphasize and rely on the standard
72 library facilities for as much as possible. Common support libraries providing
73 functionality missing from the standard library for which there are standard
74 interfaces or active work on adding standard interfaces will often be
75 implemented in the LLVM namespace following the expected standard interface.
77 There are some exceptions such as the standard I/O streams library which are
78 avoided. Also, there is much more detailed information on these subjects in the
79 :doc:`ProgrammersManual`.
81 Supported C++14 Language and Library Features
82 ---------------------------------------------
84 While LLVM, Clang, and LLD use C++14, not all features are available in all of
85 the toolchains which we support. The set of features supported for use in LLVM
86 is the intersection of those supported in the minimum requirements described
87 in the :doc:`GettingStarted` page, section `Software`.
88 The ultimate definition of this set is what build bots with those respective
89 toolchains accept. Don't argue with the build bots. However, we have some
90 guidance below to help you know what to expect.
92 Each toolchain provides a good reference for what it accepts:
94 * Clang: https://clang.llvm.org/cxx_status.html
95 * GCC: https://gcc.gnu.org/projects/cxx-status.html#cxx14
96 * MSVC: https://msdn.microsoft.com/en-us/library/hh567368.aspx
98 Other Languages
99 ---------------
101 Any code written in the Go programming language is not subject to the
102 formatting rules below. Instead, we adopt the formatting rules enforced by
103 the `gofmt`_ tool.
105 Go code should strive to be idiomatic. Two good sets of guidelines for what
106 this means are `Effective Go`_ and `Go Code Review Comments`_.
108 .. _gofmt:
109   https://golang.org/cmd/gofmt/
111 .. _Effective Go:
112   https://golang.org/doc/effective_go.html
114 .. _Go Code Review Comments:
115   https://github.com/golang/go/wiki/CodeReviewComments
117 Mechanical Source Issues
118 ========================
120 Source Code Formatting
121 ----------------------
123 Commenting
124 ^^^^^^^^^^
126 Comments are one critical part of readability and maintainability.  Everyone
127 knows they should comment their code, and so should you.  When writing comments,
128 write them as English prose, which means they should use proper capitalization,
129 punctuation, etc.  Aim to describe what the code is trying to do and why, not
130 *how* it does it at a micro level. Here are a few critical things to document:
132 .. _header file comment:
134 File Headers
135 """"""""""""
137 Every source file should have a header on it that describes the basic purpose of
138 the file.  If a file does not have a header, it should not be checked into the
139 tree.  The standard header looks like this:
141 .. code-block:: c++
143   //===-- llvm/Instruction.h - Instruction class definition -------*- C++ -*-===//
144   //
145   // Part of the LLVM Project, under the Apache License v2.0 with LLVM Exceptions.
146   // See https://llvm.org/LICENSE.txt for license information.
147   // SPDX-License-Identifier: Apache-2.0 WITH LLVM-exception
148   //
149   //===----------------------------------------------------------------------===//
150   ///
151   /// \file
152   /// This file contains the declaration of the Instruction class, which is the
153   /// base class for all of the VM instructions.
154   ///
155   //===----------------------------------------------------------------------===//
157 A few things to note about this particular format: The "``-*- C++ -*-``" string
158 on the first line is there to tell Emacs that the source file is a C++ file, not
159 a C file (Emacs assumes ``.h`` files are C files by default).
161 .. note::
163     This tag is not necessary in ``.cpp`` files.  The name of the file is also
164     on the first line, along with a very short description of the purpose of the
165     file.  This is important when printing out code and flipping though lots of
166     pages.
168 The next section in the file is a concise note that defines the license that the
169 file is released under.  This makes it perfectly clear what terms the source
170 code can be distributed under and should not be modified in any way.
172 The main body is a ``doxygen`` comment (identified by the ``///`` comment
173 marker instead of the usual ``//``) describing the purpose of the file.  The
174 first sentence (or a passage beginning with ``\brief``) is used as an abstract.
175 Any additional information should be separated by a blank line.  If an
176 algorithm is being implemented or something tricky is going on, a reference
177 to the paper where it is published should be included, as well as any notes or
178 *gotchas* in the code to watch out for.
180 Class overviews
181 """""""""""""""
183 Classes are one fundamental part of a good object oriented design.  As such, a
184 class definition should have a comment block that explains what the class is
185 used for and how it works.  Every non-trivial class is expected to have a
186 ``doxygen`` comment block.
188 Method information
189 """"""""""""""""""
191 Methods defined in a class (as well as any global functions) should also be
192 documented properly.  A quick note about what it does and a description of the
193 borderline behaviour is all that is necessary here (unless something
194 particularly tricky or insidious is going on).  The hope is that people can
195 figure out how to use your interfaces without reading the code itself.
197 Good things to talk about here are what happens when something unexpected
198 happens: does the method return null?  Abort?  Format your hard disk?
200 Comment Formatting
201 ^^^^^^^^^^^^^^^^^^
203 In general, prefer C++ style comments (``//`` for normal comments, ``///`` for
204 ``doxygen`` documentation comments).  They take less space, require
205 less typing, don't have nesting problems, etc.  There are a few cases when it is
206 useful to use C style (``/* */``) comments however:
208 #. When writing C code: Obviously if you are writing C code, use C style
209    comments.
211 #. When writing a header file that may be ``#include``\d by a C source file.
213 #. When writing a source file that is used by a tool that only accepts C style
214    comments.
216 #. When documenting the significance of constants used as actual parameters in
217    a call. This is most helpful for ``bool`` parameters, or passing ``0`` or
218    ``nullptr``. Typically you add the formal parameter name, which ought to be
219    meaningful. For example, it's not clear what the parameter means in this call:
221    .. code-block:: c++
223      Object.emitName(nullptr);
225    An in-line C-style comment makes the intent obvious:
227    .. code-block:: c++
229      Object.emitName(/*Prefix=*/nullptr);
231 Commenting out large blocks of code is discouraged, but if you really have to do
232 this (for documentation purposes or as a suggestion for debug printing), use
233 ``#if 0`` and ``#endif``. These nest properly and are better behaved in general
234 than C style comments.
236 Doxygen Use in Documentation Comments
237 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
239 Use the ``\file`` command to turn the standard file header into a file-level
240 comment.
242 Include descriptive paragraphs for all public interfaces (public classes,
243 member and non-member functions).  Don't just restate the information that can
244 be inferred from the API name.  The first sentence (or a paragraph beginning
245 with ``\brief``) is used as an abstract. Try to use a single sentence as the
246 ``\brief`` adds visual clutter.  Put detailed discussion into separate
247 paragraphs.
249 To refer to parameter names inside a paragraph, use the ``\p name`` command.
250 Don't use the ``\arg name`` command since it starts a new paragraph that
251 contains documentation for the parameter.
253 Wrap non-inline code examples in ``\code ... \endcode``.
255 To document a function parameter, start a new paragraph with the
256 ``\param name`` command.  If the parameter is used as an out or an in/out
257 parameter, use the ``\param [out] name`` or ``\param [in,out] name`` command,
258 respectively.
260 To describe function return value, start a new paragraph with the ``\returns``
261 command.
263 A minimal documentation comment:
265 .. code-block:: c++
267   /// Sets the xyzzy property to \p Baz.
268   void setXyzzy(bool Baz);
270 A documentation comment that uses all Doxygen features in a preferred way:
272 .. code-block:: c++
274   /// Does foo and bar.
275   ///
276   /// Does not do foo the usual way if \p Baz is true.
277   ///
278   /// Typical usage:
279   /// \code
280   ///   fooBar(false, "quux", Res);
281   /// \endcode
282   ///
283   /// \param Quux kind of foo to do.
284   /// \param [out] Result filled with bar sequence on foo success.
285   ///
286   /// \returns true on success.
287   bool fooBar(bool Baz, StringRef Quux, std::vector<int> &Result);
289 Don't duplicate the documentation comment in the header file and in the
290 implementation file.  Put the documentation comments for public APIs into the
291 header file.  Documentation comments for private APIs can go to the
292 implementation file.  In any case, implementation files can include additional
293 comments (not necessarily in Doxygen markup) to explain implementation details
294 as needed.
296 Don't duplicate function or class name at the beginning of the comment.
297 For humans it is obvious which function or class is being documented;
298 automatic documentation processing tools are smart enough to bind the comment
299 to the correct declaration.
301 Wrong:
303 .. code-block:: c++
305   // In Something.h:
307   /// Something - An abstraction for some complicated thing.
308   class Something {
309   public:
310     /// fooBar - Does foo and bar.
311     void fooBar();
312   };
314   // In Something.cpp:
316   /// fooBar - Does foo and bar.
317   void Something::fooBar() { ... }
319 Correct:
321 .. code-block:: c++
323   // In Something.h:
325   /// An abstraction for some complicated thing.
326   class Something {
327   public:
328     /// Does foo and bar.
329     void fooBar();
330   };
332   // In Something.cpp:
334   // Builds a B-tree in order to do foo.  See paper by...
335   void Something::fooBar() { ... }
337 It is not required to use additional Doxygen features, but sometimes it might
338 be a good idea to do so.
340 Consider:
342 * adding comments to any narrow namespace containing a collection of
343   related functions or types;
345 * using top-level groups to organize a collection of related functions at
346   namespace scope where the grouping is smaller than the namespace;
348 * using member groups and additional comments attached to member
349   groups to organize within a class.
351 For example:
353 .. code-block:: c++
355   class Something {
356     /// \name Functions that do Foo.
357     /// @{
358     void fooBar();
359     void fooBaz();
360     /// @}
361     ...
362   };
364 ``#include`` Style
365 ^^^^^^^^^^^^^^^^^^
367 Immediately after the `header file comment`_ (and include guards if working on a
368 header file), the `minimal list of #includes`_ required by the file should be
369 listed.  We prefer these ``#include``\s to be listed in this order:
371 .. _Main Module Header:
372 .. _Local/Private Headers:
374 #. Main Module Header
375 #. Local/Private Headers
376 #. LLVM project/subproject headers (``clang/...``, ``lldb/...``, ``llvm/...``, etc)
377 #. System ``#include``\s
379 and each category should be sorted lexicographically by the full path.
381 The `Main Module Header`_ file applies to ``.cpp`` files which implement an
382 interface defined by a ``.h`` file.  This ``#include`` should always be included
383 **first** regardless of where it lives on the file system.  By including a
384 header file first in the ``.cpp`` files that implement the interfaces, we ensure
385 that the header does not have any hidden dependencies which are not explicitly
386 ``#include``\d in the header, but should be. It is also a form of documentation
387 in the ``.cpp`` file to indicate where the interfaces it implements are defined.
389 LLVM project and subproject headers should be grouped from most specific to least
390 specific, for the same reasons described above.  For example, LLDB depends on
391 both clang and LLVM, and clang depends on LLVM.  So an LLDB source file should
392 include ``lldb`` headers first, followed by ``clang`` headers, followed by
393 ``llvm`` headers, to reduce the possibility (for example) of an LLDB header
394 accidentally picking up a missing include due to the previous inclusion of that
395 header in the main source file or some earlier header file.  clang should
396 similarly include its own headers before including llvm headers.  This rule
397 applies to all LLVM subprojects.
399 .. _fit into 80 columns:
401 Source Code Width
402 ^^^^^^^^^^^^^^^^^
404 Write your code to fit within 80 columns of text.  This helps those of us who
405 like to print out code and look at your code in an ``xterm`` without resizing
408 The longer answer is that there must be some limit to the width of the code in
409 order to reasonably allow developers to have multiple files side-by-side in
410 windows on a modest display.  If you are going to pick a width limit, it is
411 somewhat arbitrary but you might as well pick something standard.  Going with 90
412 columns (for example) instead of 80 columns wouldn't add any significant value
413 and would be detrimental to printing out code.  Also many other projects have
414 standardized on 80 columns, so some people have already configured their editors
415 for it (vs something else, like 90 columns).
417 This is one of many contentious issues in coding standards, but it is not up for
418 debate.
420 Whitespace
421 ^^^^^^^^^^
423 In all cases, prefer spaces to tabs in source files.  People have different
424 preferred indentation levels, and different styles of indentation that they
425 like; this is fine.  What isn't fine is that different editors/viewers expand
426 tabs out to different tab stops.  This can cause your code to look completely
427 unreadable, and it is not worth dealing with.
429 As always, follow the `Golden Rule`_ above: follow the style of
430 existing code if you are modifying and extending it.  If you like four spaces of
431 indentation, **DO NOT** do that in the middle of a chunk of code with two spaces
432 of indentation.  Also, do not reindent a whole source file: it makes for
433 incredible diffs that are absolutely worthless.
435 Do not commit changes that include trailing whitespace. If you find trailing
436 whitespace in a file, do not remove it unless you're otherwise changing that
437 line of code. Some common editors will automatically remove trailing whitespace
438 when saving a file which causes unrelated changes to appear in diffs and
439 commits.
441 Indent Code Consistently
442 ^^^^^^^^^^^^^^^^^^^^^^^^
444 Okay, in your first year of programming you were told that indentation is
445 important. If you didn't believe and internalize this then, now is the time.
446 Just do it. With the introduction of C++11, there are some new formatting
447 challenges that merit some suggestions to help have consistent, maintainable,
448 and tool-friendly formatting and indentation.
450 Format Lambdas Like Blocks Of Code
451 """"""""""""""""""""""""""""""""""
453 When formatting a multi-line lambda, format it like a block of code, that's
454 what it is. If there is only one multi-line lambda in a statement, and there
455 are no expressions lexically after it in the statement, drop the indent to the
456 standard two space indent for a block of code, as if it were an if-block opened
457 by the preceding part of the statement:
459 .. code-block:: c++
461   std::sort(foo.begin(), foo.end(), [&](Foo a, Foo b) -> bool {
462     if (a.blah < b.blah)
463       return true;
464     if (a.baz < b.baz)
465       return true;
466     return a.bam < b.bam;
467   });
469 To take best advantage of this formatting, if you are designing an API which
470 accepts a continuation or single callable argument (be it a functor, or
471 a ``std::function``), it should be the last argument if at all possible.
473 If there are multiple multi-line lambdas in a statement, or there is anything
474 interesting after the lambda in the statement, indent the block two spaces from
475 the indent of the ``[]``:
477 .. code-block:: c++
479   dyn_switch(V->stripPointerCasts(),
480              [] (PHINode *PN) {
481                // process phis...
482              },
483              [] (SelectInst *SI) {
484                // process selects...
485              },
486              [] (LoadInst *LI) {
487                // process loads...
488              },
489              [] (AllocaInst *AI) {
490                // process allocas...
491              });
493 Braced Initializer Lists
494 """"""""""""""""""""""""
496 With C++11, there are significantly more uses of braced lists to perform
497 initialization. These allow you to easily construct aggregate temporaries in
498 expressions among other niceness. They now have a natural way of ending up
499 nested within each other and within function calls in order to build up
500 aggregates (such as option structs) from local variables. To make matters
501 worse, we also have many more uses of braces in an expression context that are
502 *not* performing initialization.
504 The historically common formatting of braced initialization of aggregate
505 variables does not mix cleanly with deep nesting, general expression contexts,
506 function arguments, and lambdas. We suggest new code use a simple rule for
507 formatting braced initialization lists: act as-if the braces were parentheses
508 in a function call. The formatting rules exactly match those already well
509 understood for formatting nested function calls. Examples:
511 .. code-block:: c++
513   foo({a, b, c}, {1, 2, 3});
515   llvm::Constant *Mask[] = {
516       llvm::ConstantInt::get(llvm::Type::getInt32Ty(getLLVMContext()), 0),
517       llvm::ConstantInt::get(llvm::Type::getInt32Ty(getLLVMContext()), 1),
518       llvm::ConstantInt::get(llvm::Type::getInt32Ty(getLLVMContext()), 2)};
520 This formatting scheme also makes it particularly easy to get predictable,
521 consistent, and automatic formatting with tools like `Clang Format`_.
523 .. _Clang Format: https://clang.llvm.org/docs/ClangFormat.html
525 Language and Compiler Issues
526 ----------------------------
528 Treat Compiler Warnings Like Errors
529 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
531 If your code has compiler warnings in it, something is wrong --- you aren't
532 casting values correctly, you have "questionable" constructs in your code, or
533 you are doing something legitimately wrong.  Compiler warnings can cover up
534 legitimate errors in output and make dealing with a translation unit difficult.
536 It is not possible to prevent all warnings from all compilers, nor is it
537 desirable.  Instead, pick a standard compiler (like ``gcc``) that provides a
538 good thorough set of warnings, and stick to it.  At least in the case of
539 ``gcc``, it is possible to work around any spurious errors by changing the
540 syntax of the code slightly.  For example, a warning that annoys me occurs when
541 I write code like this:
543 .. code-block:: c++
545   if (V = getValue()) {
546     ...
547   }
549 ``gcc`` will warn me that I probably want to use the ``==`` operator, and that I
550 probably mistyped it.  In most cases, I haven't, and I really don't want the
551 spurious errors.  To fix this particular problem, I rewrite the code like
552 this:
554 .. code-block:: c++
556   if ((V = getValue())) {
557     ...
558   }
560 which shuts ``gcc`` up.  Any ``gcc`` warning that annoys you can be fixed by
561 massaging the code appropriately.
563 Write Portable Code
564 ^^^^^^^^^^^^^^^^^^^
566 In almost all cases, it is possible and within reason to write completely
567 portable code.  If there are cases where it isn't possible to write portable
568 code, isolate it behind a well defined (and well documented) interface.
570 In practice, this means that you shouldn't assume much about the host compiler
571 (and Visual Studio tends to be the lowest common denominator).  If advanced
572 features are used, they should only be an implementation detail of a library
573 which has a simple exposed API, and preferably be buried in ``libSystem``.
575 Do not use RTTI or Exceptions
576 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
578 In an effort to reduce code and executable size, LLVM does not use RTTI
579 (e.g. ``dynamic_cast<>;``) or exceptions.  These two language features violate
580 the general C++ principle of *"you only pay for what you use"*, causing
581 executable bloat even if exceptions are never used in the code base, or if RTTI
582 is never used for a class.  Because of this, we turn them off globally in the
583 code.
585 That said, LLVM does make extensive use of a hand-rolled form of RTTI that use
586 templates like :ref:`isa\<>, cast\<>, and dyn_cast\<> <isa>`.
587 This form of RTTI is opt-in and can be
588 :doc:`added to any class <HowToSetUpLLVMStyleRTTI>`. It is also
589 substantially more efficient than ``dynamic_cast<>``.
591 .. _static constructor:
593 Do not use Static Constructors
594 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
596 Static constructors and destructors (e.g. global variables whose types have a
597 constructor or destructor) should not be added to the code base, and should be
598 removed wherever possible.  Besides `well known problems
599 <https://yosefk.com/c++fqa/ctors.html#fqa-10.12>`_ where the order of
600 initialization is undefined between globals in different source files, the
601 entire concept of static constructors is at odds with the common use case of
602 LLVM as a library linked into a larger application.
603   
604 Consider the use of LLVM as a JIT linked into another application (perhaps for
605 `OpenGL, custom languages <https://llvm.org/Users.html>`_, `shaders in movies
606 <https://llvm.org/devmtg/2010-11/Gritz-OpenShadingLang.pdf>`_, etc). Due to the
607 design of static constructors, they must be executed at startup time of the
608 entire application, regardless of whether or how LLVM is used in that larger
609 application.  There are two problems with this:
611 * The time to run the static constructors impacts startup time of applications
612   --- a critical time for GUI apps, among others.
613   
614 * The static constructors cause the app to pull many extra pages of memory off
615   the disk: both the code for the constructor in each ``.o`` file and the small
616   amount of data that gets touched. In addition, touched/dirty pages put more
617   pressure on the VM system on low-memory machines.
619 We would really like for there to be zero cost for linking in an additional LLVM
620 target or other library into an application, but static constructors violate
621 this goal.
622   
623 That said, LLVM unfortunately does contain static constructors.  It would be a
624 `great project <https://llvm.org/PR11944>`_ for someone to purge all static
625 constructors from LLVM, and then enable the ``-Wglobal-constructors`` warning
626 flag (when building with Clang) to ensure we do not regress in the future.
628 Use of ``class`` and ``struct`` Keywords
629 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
631 In C++, the ``class`` and ``struct`` keywords can be used almost
632 interchangeably. The only difference is when they are used to declare a class:
633 ``class`` makes all members private by default while ``struct`` makes all
634 members public by default.
636 Unfortunately, not all compilers follow the rules and some will generate
637 different symbols based on whether ``class`` or ``struct`` was used to declare
638 the symbol (e.g., MSVC).  This can lead to problems at link time.
640 * All declarations and definitions of a given ``class`` or ``struct`` must use
641   the same keyword.  For example:
643 .. code-block:: c++
645   class Foo;
647   // Breaks mangling in MSVC.
648   struct Foo { int Data; };
650 * As a rule of thumb, ``struct`` should be kept to structures where *all*
651   members are declared public.
653 .. code-block:: c++
655   // Foo feels like a class... this is strange.
656   struct Foo {
657   private:
658     int Data;
659   public:
660     Foo() : Data(0) { }
661     int getData() const { return Data; }
662     void setData(int D) { Data = D; }
663   };
665   // Bar isn't POD, but it does look like a struct.
666   struct Bar {
667     int Data;
668     Bar() : Data(0) { }
669   };
671 Do not use Braced Initializer Lists to Call a Constructor
672 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
674 In C++11 there is a "generalized initialization syntax" which allows calling
675 constructors using braced initializer lists. Do not use these to call
676 constructors with any interesting logic or if you care that you're calling some
677 *particular* constructor. Those should look like function calls using
678 parentheses rather than like aggregate initialization. Similarly, if you need
679 to explicitly name the type and call its constructor to create a temporary,
680 don't use a braced initializer list. Instead, use a braced initializer list
681 (without any type for temporaries) when doing aggregate initialization or
682 something notionally equivalent. Examples:
684 .. code-block:: c++
686   class Foo {
687   public:
688     // Construct a Foo by reading data from the disk in the whizbang format, ...
689     Foo(std::string filename);
691     // Construct a Foo by looking up the Nth element of some global data ...
692     Foo(int N);
694     // ...
695   };
697   // The Foo constructor call is very deliberate, no braces.
698   std::fill(foo.begin(), foo.end(), Foo("name"));
700   // The pair is just being constructed like an aggregate, use braces.
701   bar_map.insert({my_key, my_value});
703 If you use a braced initializer list when initializing a variable, use an equals before the open curly brace:
705 .. code-block:: c++
707   int data[] = {0, 1, 2, 3};
709 Use ``auto`` Type Deduction to Make Code More Readable
710 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
712 Some are advocating a policy of "almost always ``auto``" in C++11, however LLVM
713 uses a more moderate stance. Use ``auto`` if and only if it makes the code more
714 readable or easier to maintain. Don't "almost always" use ``auto``, but do use
715 ``auto`` with initializers like ``cast<Foo>(...)`` or other places where the
716 type is already obvious from the context. Another time when ``auto`` works well
717 for these purposes is when the type would have been abstracted away anyways,
718 often behind a container's typedef such as ``std::vector<T>::iterator``.
720 Similarly, C++14 adds generic lambda expressions where parameter types can be
721 ``auto``. Use these where you would have used a template.
723 Beware unnecessary copies with ``auto``
724 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
726 The convenience of ``auto`` makes it easy to forget that its default behavior
727 is a copy.  Particularly in range-based ``for`` loops, careless copies are
728 expensive.
730 As a rule of thumb, use ``auto &`` unless you need to copy the result, and use
731 ``auto *`` when copying pointers.
733 .. code-block:: c++
735   // Typically there's no reason to copy.
736   for (const auto &Val : Container) { observe(Val); }
737   for (auto &Val : Container) { Val.change(); }
739   // Remove the reference if you really want a new copy.
740   for (auto Val : Container) { Val.change(); saveSomewhere(Val); }
742   // Copy pointers, but make it clear that they're pointers.
743   for (const auto *Ptr : Container) { observe(*Ptr); }
744   for (auto *Ptr : Container) { Ptr->change(); }
746 Beware of non-determinism due to ordering of pointers
747 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
749 In general, there is no relative ordering among pointers. As a result,
750 when unordered containers like sets and maps are used with pointer keys
751 the iteration order is undefined. Hence, iterating such containers may
752 result in non-deterministic code generation. While the generated code
753 might not necessarily be "wrong code", this non-determinism might result
754 in unexpected runtime crashes or simply hard to reproduce bugs on the
755 customer side making it harder to debug and fix.
757 As a rule of thumb, in case an ordered result is expected, remember to
758 sort an unordered container before iteration. Or use ordered containers
759 like vector/MapVector/SetVector if you want to iterate pointer keys.
761 Beware of non-deterministic sorting order of equal elements
762 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
764 std::sort uses a non-stable sorting algorithm in which the order of equal
765 elements is not guaranteed to be preserved. Thus using std::sort for a
766 container having equal elements may result in non-determinstic behavior.
767 To uncover such instances of non-determinism, LLVM has introduced a new
768 llvm::sort wrapper function. For an EXPENSIVE_CHECKS build this will randomly
769 shuffle the container before sorting. As a rule of thumb, always make sure to
770 use llvm::sort instead of std::sort.
772 Style Issues
773 ============
775 The High-Level Issues
776 ---------------------
778 Self-contained Headers
779 ^^^^^^^^^^^^^^^^^^^^^^
781 Header files should be self-contained (compile on their own) and end in .h.
782 Non-header files that are meant for inclusion should end in .inc and be used
783 sparingly.
785 All header files should be self-contained. Users and refactoring tools should
786 not have to adhere to special conditions to include the header. Specifically, a
787 header should have header guards and include all other headers it needs.
789 There are rare cases where a file designed to be included is not
790 self-contained. These are typically intended to be included at unusual
791 locations, such as the middle of another file. They might not use header
792 guards, and might not include their prerequisites. Name such files with the
793 .inc extension. Use sparingly, and prefer self-contained headers when possible.
795 In general, a header should be implemented by one or more ``.cpp`` files.  Each
796 of these ``.cpp`` files should include the header that defines their interface
797 first.  This ensures that all of the dependences of the header have been
798 properly added to the header itself, and are not implicit.  System headers
799 should be included after user headers for a translation unit.
801 Library Layering
802 ^^^^^^^^^^^^^^^^
804 A directory of header files (for example ``include/llvm/Foo``) defines a
805 library (``Foo``). Dependencies between libraries are defined by the
806 ``LLVMBuild.txt`` file in their implementation (``lib/Foo``). One library (both
807 its headers and implementation) should only use things from the libraries
808 listed in its dependencies.
810 Some of this constraint can be enforced by classic Unix linkers (Mac & Windows
811 linkers, as well as lld, do not enforce this constraint). A Unix linker
812 searches left to right through the libraries specified on its command line and
813 never revisits a library. In this way, no circular dependencies between
814 libraries can exist.
816 This doesn't fully enforce all inter-library dependencies, and importantly
817 doesn't enforce header file circular dependencies created by inline functions.
818 A good way to answer the "is this layered correctly" would be to consider
819 whether a Unix linker would succeed at linking the program if all inline
820 functions were defined out-of-line. (& for all valid orderings of dependencies
821 - since linking resolution is linear, it's possible that some implicit
822 dependencies can sneak through: A depends on B and C, so valid orderings are
823 "C B A" or "B C A", in both cases the explicit dependencies come before their
824 use. But in the first case, B could still link successfully if it implicitly
825 depended on C, or the opposite in the second case)
827 .. _minimal list of #includes:
829 ``#include`` as Little as Possible
830 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
832 ``#include`` hurts compile time performance.  Don't do it unless you have to,
833 especially in header files.
835 But wait! Sometimes you need to have the definition of a class to use it, or to
836 inherit from it.  In these cases go ahead and ``#include`` that header file.  Be
837 aware however that there are many cases where you don't need to have the full
838 definition of a class.  If you are using a pointer or reference to a class, you
839 don't need the header file.  If you are simply returning a class instance from a
840 prototyped function or method, you don't need it.  In fact, for most cases, you
841 simply don't need the definition of a class. And not ``#include``\ing speeds up
842 compilation.
844 It is easy to try to go too overboard on this recommendation, however.  You
845 **must** include all of the header files that you are using --- you can include
846 them either directly or indirectly through another header file.  To make sure
847 that you don't accidentally forget to include a header file in your module
848 header, make sure to include your module header **first** in the implementation
849 file (as mentioned above).  This way there won't be any hidden dependencies that
850 you'll find out about later.
852 Keep "Internal" Headers Private
853 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
855 Many modules have a complex implementation that causes them to use more than one
856 implementation (``.cpp``) file.  It is often tempting to put the internal
857 communication interface (helper classes, extra functions, etc) in the public
858 module header file.  Don't do this!
860 If you really need to do something like this, put a private header file in the
861 same directory as the source files, and include it locally.  This ensures that
862 your private interface remains private and undisturbed by outsiders.
864 .. note::
866     It's okay to put extra implementation methods in a public class itself. Just
867     make them private (or protected) and all is well.
869 .. _early exits:
871 Use Early Exits and ``continue`` to Simplify Code
872 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
874 When reading code, keep in mind how much state and how many previous decisions
875 have to be remembered by the reader to understand a block of code.  Aim to
876 reduce indentation where possible when it doesn't make it more difficult to
877 understand the code.  One great way to do this is by making use of early exits
878 and the ``continue`` keyword in long loops.  As an example of using an early
879 exit from a function, consider this "bad" code:
881 .. code-block:: c++
883   Value *doSomething(Instruction *I) {
884     if (!I->isTerminator() &&
885         I->hasOneUse() && doOtherThing(I)) {
886       ... some long code ....
887     }
889     return 0;
890   }
892 This code has several problems if the body of the ``'if'`` is large.  When
893 you're looking at the top of the function, it isn't immediately clear that this
894 *only* does interesting things with non-terminator instructions, and only
895 applies to things with the other predicates.  Second, it is relatively difficult
896 to describe (in comments) why these predicates are important because the ``if``
897 statement makes it difficult to lay out the comments.  Third, when you're deep
898 within the body of the code, it is indented an extra level.  Finally, when
899 reading the top of the function, it isn't clear what the result is if the
900 predicate isn't true; you have to read to the end of the function to know that
901 it returns null.
903 It is much preferred to format the code like this:
905 .. code-block:: c++
907   Value *doSomething(Instruction *I) {
908     // Terminators never need 'something' done to them because ... 
909     if (I->isTerminator())
910       return 0;
912     // We conservatively avoid transforming instructions with multiple uses
913     // because goats like cheese.
914     if (!I->hasOneUse())
915       return 0;
917     // This is really just here for example.
918     if (!doOtherThing(I))
919       return 0;
920     
921     ... some long code ....
922   }
924 This fixes these problems.  A similar problem frequently happens in ``for``
925 loops.  A silly example is something like this:
927 .. code-block:: c++
929   for (Instruction &I : BB) {
930     if (auto *BO = dyn_cast<BinaryOperator>(&I)) {
931       Value *LHS = BO->getOperand(0);
932       Value *RHS = BO->getOperand(1);
933       if (LHS != RHS) {
934         ...
935       }
936     }
937   }
939 When you have very, very small loops, this sort of structure is fine. But if it
940 exceeds more than 10-15 lines, it becomes difficult for people to read and
941 understand at a glance. The problem with this sort of code is that it gets very
942 nested very quickly. Meaning that the reader of the code has to keep a lot of
943 context in their brain to remember what is going immediately on in the loop,
944 because they don't know if/when the ``if`` conditions will have ``else``\s etc.
945 It is strongly preferred to structure the loop like this:
947 .. code-block:: c++
949   for (Instruction &I : BB) {
950     auto *BO = dyn_cast<BinaryOperator>(&I);
951     if (!BO) continue;
953     Value *LHS = BO->getOperand(0);
954     Value *RHS = BO->getOperand(1);
955     if (LHS == RHS) continue;
957     ...
958   }
960 This has all the benefits of using early exits for functions: it reduces nesting
961 of the loop, it makes it easier to describe why the conditions are true, and it
962 makes it obvious to the reader that there is no ``else`` coming up that they
963 have to push context into their brain for.  If a loop is large, this can be a
964 big understandability win.
966 Don't use ``else`` after a ``return``
967 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
969 For similar reasons above (reduction of indentation and easier reading), please
970 do not use ``'else'`` or ``'else if'`` after something that interrupts control
971 flow --- like ``return``, ``break``, ``continue``, ``goto``, etc. For
972 example, this is *bad*:
974 .. code-block:: c++
976   case 'J': {
977     if (Signed) {
978       Type = Context.getsigjmp_bufType();
979       if (Type.isNull()) {
980         Error = ASTContext::GE_Missing_sigjmp_buf;
981         return QualType();
982       } else {
983         break;
984       }
985     } else {
986       Type = Context.getjmp_bufType();
987       if (Type.isNull()) {
988         Error = ASTContext::GE_Missing_jmp_buf;
989         return QualType();
990       } else {
991         break;
992       }
993     }
994   }
996 It is better to write it like this:
998 .. code-block:: c++
1000   case 'J':
1001     if (Signed) {
1002       Type = Context.getsigjmp_bufType();
1003       if (Type.isNull()) {
1004         Error = ASTContext::GE_Missing_sigjmp_buf;
1005         return QualType();
1006       }
1007     } else {
1008       Type = Context.getjmp_bufType();
1009       if (Type.isNull()) {
1010         Error = ASTContext::GE_Missing_jmp_buf;
1011         return QualType();
1012       }
1013     }
1014     break;
1016 Or better yet (in this case) as:
1018 .. code-block:: c++
1020   case 'J':
1021     if (Signed)
1022       Type = Context.getsigjmp_bufType();
1023     else
1024       Type = Context.getjmp_bufType();
1025     
1026     if (Type.isNull()) {
1027       Error = Signed ? ASTContext::GE_Missing_sigjmp_buf :
1028                        ASTContext::GE_Missing_jmp_buf;
1029       return QualType();
1030     }
1031     break;
1033 The idea is to reduce indentation and the amount of code you have to keep track
1034 of when reading the code.
1035               
1036 Turn Predicate Loops into Predicate Functions
1037 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1039 It is very common to write small loops that just compute a boolean value.  There
1040 are a number of ways that people commonly write these, but an example of this
1041 sort of thing is:
1043 .. code-block:: c++
1045   bool FoundFoo = false;
1046   for (unsigned I = 0, E = BarList.size(); I != E; ++I)
1047     if (BarList[I]->isFoo()) {
1048       FoundFoo = true;
1049       break;
1050     }
1052   if (FoundFoo) {
1053     ...
1054   }
1056 This sort of code is awkward to write, and is almost always a bad sign.  Instead
1057 of this sort of loop, we strongly prefer to use a predicate function (which may
1058 be `static`_) that uses `early exits`_ to compute the predicate.  We prefer the
1059 code to be structured like this:
1061 .. code-block:: c++
1063   /// \returns true if the specified list has an element that is a foo.
1064   static bool containsFoo(const std::vector<Bar*> &List) {
1065     for (unsigned I = 0, E = List.size(); I != E; ++I)
1066       if (List[I]->isFoo())
1067         return true;
1068     return false;
1069   }
1070   ...
1072   if (containsFoo(BarList)) {
1073     ...
1074   }
1076 There are many reasons for doing this: it reduces indentation and factors out
1077 code which can often be shared by other code that checks for the same predicate.
1078 More importantly, it *forces you to pick a name* for the function, and forces
1079 you to write a comment for it.  In this silly example, this doesn't add much
1080 value.  However, if the condition is complex, this can make it a lot easier for
1081 the reader to understand the code that queries for this predicate.  Instead of
1082 being faced with the in-line details of how we check to see if the BarList
1083 contains a foo, we can trust the function name and continue reading with better
1084 locality.
1086 The Low-Level Issues
1087 --------------------
1089 Name Types, Functions, Variables, and Enumerators Properly
1090 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1092 Poorly-chosen names can mislead the reader and cause bugs. We cannot stress
1093 enough how important it is to use *descriptive* names.  Pick names that match
1094 the semantics and role of the underlying entities, within reason.  Avoid
1095 abbreviations unless they are well known.  After picking a good name, make sure
1096 to use consistent capitalization for the name, as inconsistency requires clients
1097 to either memorize the APIs or to look it up to find the exact spelling.
1099 In general, names should be in camel case (e.g. ``TextFileReader`` and
1100 ``isLValue()``).  Different kinds of declarations have different rules:
1102 * **Type names** (including classes, structs, enums, typedefs, etc) should be
1103   nouns and start with an upper-case letter (e.g. ``TextFileReader``).
1105 * **Variable names** should be nouns (as they represent state).  The name should
1106   be camel case, and start with an upper case letter (e.g. ``Leader`` or
1107   ``Boats``).
1108   
1109 * **Function names** should be verb phrases (as they represent actions), and
1110   command-like function should be imperative.  The name should be camel case,
1111   and start with a lower case letter (e.g. ``openFile()`` or ``isFoo()``).
1113 * **Enum declarations** (e.g. ``enum Foo {...}``) are types, so they should
1114   follow the naming conventions for types.  A common use for enums is as a
1115   discriminator for a union, or an indicator of a subclass.  When an enum is
1116   used for something like this, it should have a ``Kind`` suffix
1117   (e.g. ``ValueKind``).
1118   
1119 * **Enumerators** (e.g. ``enum { Foo, Bar }``) and **public member variables**
1120   should start with an upper-case letter, just like types.  Unless the
1121   enumerators are defined in their own small namespace or inside a class,
1122   enumerators should have a prefix corresponding to the enum declaration name.
1123   For example, ``enum ValueKind { ... };`` may contain enumerators like
1124   ``VK_Argument``, ``VK_BasicBlock``, etc.  Enumerators that are just
1125   convenience constants are exempt from the requirement for a prefix.  For
1126   instance:
1128   .. code-block:: c++
1130       enum {
1131         MaxSize = 42,
1132         Density = 12
1133       };
1134   
1135 As an exception, classes that mimic STL classes can have member names in STL's
1136 style of lower-case words separated by underscores (e.g. ``begin()``,
1137 ``push_back()``, and ``empty()``). Classes that provide multiple
1138 iterators should add a singular prefix to ``begin()`` and ``end()``
1139 (e.g. ``global_begin()`` and ``use_begin()``).
1141 Here are some examples of good and bad names:
1143 .. code-block:: c++
1145   class VehicleMaker {
1146     ...
1147     Factory<Tire> F;            // Bad -- abbreviation and non-descriptive.
1148     Factory<Tire> Factory;      // Better.
1149     Factory<Tire> TireFactory;  // Even better -- if VehicleMaker has more than one
1150                                 // kind of factories.
1151   };
1153   Vehicle makeVehicle(VehicleType Type) {
1154     VehicleMaker M;                         // Might be OK if having a short life-span.
1155     Tire Tmp1 = M.makeTire();               // Bad -- 'Tmp1' provides no information.
1156     Light Headlight = M.makeLight("head");  // Good -- descriptive.
1157     ...
1158   }
1160 Assert Liberally
1161 ^^^^^^^^^^^^^^^^
1163 Use the "``assert``" macro to its fullest.  Check all of your preconditions and
1164 assumptions, you never know when a bug (not necessarily even yours) might be
1165 caught early by an assertion, which reduces debugging time dramatically.  The
1166 "``<cassert>``" header file is probably already included by the header files you
1167 are using, so it doesn't cost anything to use it.
1169 To further assist with debugging, make sure to put some kind of error message in
1170 the assertion statement, which is printed if the assertion is tripped. This
1171 helps the poor debugger make sense of why an assertion is being made and
1172 enforced, and hopefully what to do about it.  Here is one complete example:
1174 .. code-block:: c++
1176   inline Value *getOperand(unsigned I) {
1177     assert(I < Operands.size() && "getOperand() out of range!");
1178     return Operands[I];
1179   }
1181 Here are more examples:
1183 .. code-block:: c++
1185   assert(Ty->isPointerType() && "Can't allocate a non-pointer type!");
1187   assert((Opcode == Shl || Opcode == Shr) && "ShiftInst Opcode invalid!");
1189   assert(idx < getNumSuccessors() && "Successor # out of range!");
1191   assert(V1.getType() == V2.getType() && "Constant types must be identical!");
1193   assert(isa<PHINode>(Succ->front()) && "Only works on PHId BBs!");
1195 You get the idea.
1197 In the past, asserts were used to indicate a piece of code that should not be
1198 reached.  These were typically of the form:
1200 .. code-block:: c++
1202   assert(0 && "Invalid radix for integer literal");
1204 This has a few issues, the main one being that some compilers might not
1205 understand the assertion, or warn about a missing return in builds where
1206 assertions are compiled out.
1208 Today, we have something much better: ``llvm_unreachable``:
1210 .. code-block:: c++
1212   llvm_unreachable("Invalid radix for integer literal");
1214 When assertions are enabled, this will print the message if it's ever reached
1215 and then exit the program. When assertions are disabled (i.e. in release
1216 builds), ``llvm_unreachable`` becomes a hint to compilers to skip generating
1217 code for this branch. If the compiler does not support this, it will fall back
1218 to the "abort" implementation.
1220 Neither assertions or ``llvm_unreachable`` will abort the program on a release
1221 build. If the error condition can be triggered by user input then the
1222 recoverable error mechanism described in :doc:`ProgrammersManual` should be
1223 used instead. In cases where this is not practical, ``report_fatal_error`` may
1224 be used.
1226 Another issue is that values used only by assertions will produce an "unused
1227 value" warning when assertions are disabled.  For example, this code will warn:
1229 .. code-block:: c++
1231   unsigned Size = V.size();
1232   assert(Size > 42 && "Vector smaller than it should be");
1234   bool NewToSet = Myset.insert(Value);
1235   assert(NewToSet && "The value shouldn't be in the set yet");
1237 These are two interesting different cases. In the first case, the call to
1238 ``V.size()`` is only useful for the assert, and we don't want it executed when
1239 assertions are disabled.  Code like this should move the call into the assert
1240 itself.  In the second case, the side effects of the call must happen whether
1241 the assert is enabled or not.  In this case, the value should be cast to void to
1242 disable the warning.  To be specific, it is preferred to write the code like
1243 this:
1245 .. code-block:: c++
1247   assert(V.size() > 42 && "Vector smaller than it should be");
1249   bool NewToSet = Myset.insert(Value); (void)NewToSet;
1250   assert(NewToSet && "The value shouldn't be in the set yet");
1252 Do Not Use ``using namespace std``
1253 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1255 In LLVM, we prefer to explicitly prefix all identifiers from the standard
1256 namespace with an "``std::``" prefix, rather than rely on "``using namespace
1257 std;``".
1259 In header files, adding a ``'using namespace XXX'`` directive pollutes the
1260 namespace of any source file that ``#include``\s the header.  This is clearly a
1261 bad thing.
1263 In implementation files (e.g. ``.cpp`` files), the rule is more of a stylistic
1264 rule, but is still important.  Basically, using explicit namespace prefixes
1265 makes the code **clearer**, because it is immediately obvious what facilities
1266 are being used and where they are coming from. And **more portable**, because
1267 namespace clashes cannot occur between LLVM code and other namespaces.  The
1268 portability rule is important because different standard library implementations
1269 expose different symbols (potentially ones they shouldn't), and future revisions
1270 to the C++ standard will add more symbols to the ``std`` namespace.  As such, we
1271 never use ``'using namespace std;'`` in LLVM.
1273 The exception to the general rule (i.e. it's not an exception for the ``std``
1274 namespace) is for implementation files.  For example, all of the code in the
1275 LLVM project implements code that lives in the 'llvm' namespace.  As such, it is
1276 ok, and actually clearer, for the ``.cpp`` files to have a ``'using namespace
1277 llvm;'`` directive at the top, after the ``#include``\s.  This reduces
1278 indentation in the body of the file for source editors that indent based on
1279 braces, and keeps the conceptual context cleaner.  The general form of this rule
1280 is that any ``.cpp`` file that implements code in any namespace may use that
1281 namespace (and its parents'), but should not use any others.
1283 Provide a Virtual Method Anchor for Classes in Headers
1284 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1286 If a class is defined in a header file and has a vtable (either it has virtual
1287 methods or it derives from classes with virtual methods), it must always have at
1288 least one out-of-line virtual method in the class.  Without this, the compiler
1289 will copy the vtable and RTTI into every ``.o`` file that ``#include``\s the
1290 header, bloating ``.o`` file sizes and increasing link times.
1292 Don't use default labels in fully covered switches over enumerations
1293 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1295 ``-Wswitch`` warns if a switch, without a default label, over an enumeration
1296 does not cover every enumeration value. If you write a default label on a fully
1297 covered switch over an enumeration then the ``-Wswitch`` warning won't fire
1298 when new elements are added to that enumeration. To help avoid adding these
1299 kinds of defaults, Clang has the warning ``-Wcovered-switch-default`` which is
1300 off by default but turned on when building LLVM with a version of Clang that
1301 supports the warning.
1303 A knock-on effect of this stylistic requirement is that when building LLVM with
1304 GCC you may get warnings related to "control may reach end of non-void function"
1305 if you return from each case of a covered switch-over-enum because GCC assumes
1306 that the enum expression may take any representable value, not just those of
1307 individual enumerators. To suppress this warning, use ``llvm_unreachable`` after
1308 the switch.
1310 Use range-based ``for`` loops wherever possible
1311 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1313 The introduction of range-based ``for`` loops in C++11 means that explicit
1314 manipulation of iterators is rarely necessary. We use range-based ``for``
1315 loops wherever possible for all newly added code. For example:
1317 .. code-block:: c++
1319   BasicBlock *BB = ...
1320   for (Instruction &I : *BB)
1321     ... use I ...
1323 Don't evaluate ``end()`` every time through a loop
1324 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1326 In cases where range-based ``for`` loops can't be used and it is necessary
1327 to write an explicit iterator-based loop, pay close attention to whether
1328 ``end()`` is re-evaluted on each loop iteration. One common mistake is to
1329 write a loop in this style:
1331 .. code-block:: c++
1333   BasicBlock *BB = ...
1334   for (auto I = BB->begin(); I != BB->end(); ++I)
1335     ... use I ...
1337 The problem with this construct is that it evaluates "``BB->end()``" every time
1338 through the loop.  Instead of writing the loop like this, we strongly prefer
1339 loops to be written so that they evaluate it once before the loop starts.  A
1340 convenient way to do this is like so:
1342 .. code-block:: c++
1344   BasicBlock *BB = ...
1345   for (auto I = BB->begin(), E = BB->end(); I != E; ++I)
1346     ... use I ...
1348 The observant may quickly point out that these two loops may have different
1349 semantics: if the container (a basic block in this case) is being mutated, then
1350 "``BB->end()``" may change its value every time through the loop and the second
1351 loop may not in fact be correct.  If you actually do depend on this behavior,
1352 please write the loop in the first form and add a comment indicating that you
1353 did it intentionally.
1355 Why do we prefer the second form (when correct)?  Writing the loop in the first
1356 form has two problems. First it may be less efficient than evaluating it at the
1357 start of the loop.  In this case, the cost is probably minor --- a few extra
1358 loads every time through the loop.  However, if the base expression is more
1359 complex, then the cost can rise quickly.  I've seen loops where the end
1360 expression was actually something like: "``SomeMap[X]->end()``" and map lookups
1361 really aren't cheap.  By writing it in the second form consistently, you
1362 eliminate the issue entirely and don't even have to think about it.
1364 The second (even bigger) issue is that writing the loop in the first form hints
1365 to the reader that the loop is mutating the container (a fact that a comment
1366 would handily confirm!).  If you write the loop in the second form, it is
1367 immediately obvious without even looking at the body of the loop that the
1368 container isn't being modified, which makes it easier to read the code and
1369 understand what it does.
1371 While the second form of the loop is a few extra keystrokes, we do strongly
1372 prefer it.
1374 ``#include <iostream>`` is Forbidden
1375 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1377 The use of ``#include <iostream>`` in library files is hereby **forbidden**,
1378 because many common implementations transparently inject a `static constructor`_
1379 into every translation unit that includes it.
1380   
1381 Note that using the other stream headers (``<sstream>`` for example) is not
1382 problematic in this regard --- just ``<iostream>``. However, ``raw_ostream``
1383 provides various APIs that are better performing for almost every use than
1384 ``std::ostream`` style APIs.
1386 .. note::
1388   New code should always use `raw_ostream`_ for writing, or the
1389   ``llvm::MemoryBuffer`` API for reading files.
1391 .. _raw_ostream:
1393 Use ``raw_ostream``
1394 ^^^^^^^^^^^^^^^^^^^
1396 LLVM includes a lightweight, simple, and efficient stream implementation in
1397 ``llvm/Support/raw_ostream.h``, which provides all of the common features of
1398 ``std::ostream``.  All new code should use ``raw_ostream`` instead of
1399 ``ostream``.
1401 Unlike ``std::ostream``, ``raw_ostream`` is not a template and can be forward
1402 declared as ``class raw_ostream``.  Public headers should generally not include
1403 the ``raw_ostream`` header, but use forward declarations and constant references
1404 to ``raw_ostream`` instances.
1406 Avoid ``std::endl``
1407 ^^^^^^^^^^^^^^^^^^^
1409 The ``std::endl`` modifier, when used with ``iostreams`` outputs a newline to
1410 the output stream specified.  In addition to doing this, however, it also
1411 flushes the output stream.  In other words, these are equivalent:
1413 .. code-block:: c++
1415   std::cout << std::endl;
1416   std::cout << '\n' << std::flush;
1418 Most of the time, you probably have no reason to flush the output stream, so
1419 it's better to use a literal ``'\n'``.
1421 Don't use ``inline`` when defining a function in a class definition
1422 ^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^^
1424 A member function defined in a class definition is implicitly inline, so don't
1425 put the ``inline`` keyword in this case.
1427 Don't:
1429 .. code-block:: c++
1431   class Foo {
1432   public:
1433     inline void bar() {
1434       // ...
1435     }
1436   };
1440 .. code-block:: c++
1442   class Foo {
1443   public:
1444     void bar() {
1445       // ...
1446     }
1447   };
1449 Microscopic Details
1450 -------------------
1452 This section describes preferred low-level formatting guidelines along with
1453 reasoning on why we prefer them.
1455 Spaces Before Parentheses
1456 ^^^^^^^^^^^^^^^^^^^^^^^^^
1458 We prefer to put a space before an open parenthesis only in control flow
1459 statements, but not in normal function call expressions and function-like
1460 macros.  For example, this is good:
1462 .. code-block:: c++
1464   if (X) ...
1465   for (I = 0; I != 100; ++I) ...
1466   while (LLVMRocks) ...
1468   somefunc(42);
1469   assert(3 != 4 && "laws of math are failing me");
1470   
1471   A = foo(42, 92) + bar(X);
1473 and this is bad:
1475 .. code-block:: c++
1477   if(X) ...
1478   for(I = 0; I != 100; ++I) ...
1479   while(LLVMRocks) ...
1481   somefunc (42);
1482   assert (3 != 4 && "laws of math are failing me");
1483   
1484   A = foo (42, 92) + bar (X);
1486 The reason for doing this is not completely arbitrary.  This style makes control
1487 flow operators stand out more, and makes expressions flow better. The function
1488 call operator binds very tightly as a postfix operator.  Putting a space after a
1489 function name (as in the last example) makes it appear that the code might bind
1490 the arguments of the left-hand-side of a binary operator with the argument list
1491 of a function and the name of the right side.  More specifically, it is easy to
1492 misread the "``A``" example as:
1494 .. code-block:: c++
1496   A = foo ((42, 92) + bar) (X);
1498 when skimming through the code.  By avoiding a space in a function, we avoid
1499 this misinterpretation.
1501 Prefer Preincrement
1502 ^^^^^^^^^^^^^^^^^^^
1504 Hard fast rule: Preincrement (``++X``) may be no slower than postincrement
1505 (``X++``) and could very well be a lot faster than it.  Use preincrementation
1506 whenever possible.
1508 The semantics of postincrement include making a copy of the value being
1509 incremented, returning it, and then preincrementing the "work value".  For
1510 primitive types, this isn't a big deal. But for iterators, it can be a huge
1511 issue (for example, some iterators contains stack and set objects in them...
1512 copying an iterator could invoke the copy ctor's of these as well).  In general,
1513 get in the habit of always using preincrement, and you won't have a problem.
1516 Namespace Indentation
1517 ^^^^^^^^^^^^^^^^^^^^^
1519 In general, we strive to reduce indentation wherever possible.  This is useful
1520 because we want code to `fit into 80 columns`_ without wrapping horribly, but
1521 also because it makes it easier to understand the code. To facilitate this and
1522 avoid some insanely deep nesting on occasion, don't indent namespaces. If it
1523 helps readability, feel free to add a comment indicating what namespace is
1524 being closed by a ``}``.  For example:
1526 .. code-block:: c++
1528   namespace llvm {
1529   namespace knowledge {
1531   /// This class represents things that Smith can have an intimate
1532   /// understanding of and contains the data associated with it.
1533   class Grokable {
1534   ...
1535   public:
1536     explicit Grokable() { ... }
1537     virtual ~Grokable() = 0;
1538   
1539     ...
1541   };
1543   } // end namespace knowledge
1544   } // end namespace llvm
1547 Feel free to skip the closing comment when the namespace being closed is
1548 obvious for any reason. For example, the outer-most namespace in a header file
1549 is rarely a source of confusion. But namespaces both anonymous and named in
1550 source files that are being closed half way through the file probably could use
1551 clarification.
1553 .. _static:
1555 Anonymous Namespaces
1556 ^^^^^^^^^^^^^^^^^^^^
1558 After talking about namespaces in general, you may be wondering about anonymous
1559 namespaces in particular.  Anonymous namespaces are a great language feature
1560 that tells the C++ compiler that the contents of the namespace are only visible
1561 within the current translation unit, allowing more aggressive optimization and
1562 eliminating the possibility of symbol name collisions.  Anonymous namespaces are
1563 to C++ as "static" is to C functions and global variables.  While "``static``"
1564 is available in C++, anonymous namespaces are more general: they can make entire
1565 classes private to a file.
1567 The problem with anonymous namespaces is that they naturally want to encourage
1568 indentation of their body, and they reduce locality of reference: if you see a
1569 random function definition in a C++ file, it is easy to see if it is marked
1570 static, but seeing if it is in an anonymous namespace requires scanning a big
1571 chunk of the file.
1573 Because of this, we have a simple guideline: make anonymous namespaces as small
1574 as possible, and only use them for class declarations.  For example, this is
1575 good:
1577 .. code-block:: c++
1579   namespace {
1580   class StringSort {
1581   ...
1582   public:
1583     StringSort(...)
1584     bool operator<(const char *RHS) const;
1585   };
1586   } // end anonymous namespace
1588   static void runHelper() { 
1589     ... 
1590   }
1592   bool StringSort::operator<(const char *RHS) const {
1593     ...
1594   }
1596 This is bad:
1598 .. code-block:: c++
1600   namespace {
1602   class StringSort {
1603   ...
1604   public:
1605     StringSort(...)
1606     bool operator<(const char *RHS) const;
1607   };
1609   void runHelper() { 
1610     ... 
1611   }
1613   bool StringSort::operator<(const char *RHS) const {
1614     ...
1615   }
1617   } // end anonymous namespace
1619 This is bad specifically because if you're looking at "``runHelper``" in the middle
1620 of a large C++ file, that you have no immediate way to tell if it is local to
1621 the file.  When it is marked static explicitly, this is immediately obvious.
1622 Also, there is no reason to enclose the definition of "``operator<``" in the
1623 namespace just because it was declared there.
1625 See Also
1626 ========
1628 A lot of these comments and recommendations have been culled from other sources.
1629 Two particularly important books for our work are:
1631 #. `Effective C++
1632    <https://www.amazon.com/Effective-Specific-Addison-Wesley-Professional-Computing/dp/0321334876>`_
1633    by Scott Meyers.  Also interesting and useful are "More Effective C++" and
1634    "Effective STL" by the same author.
1636 #. `Large-Scale C++ Software Design
1637    <https://www.amazon.com/Large-Scale-Software-Design-John-Lakos/dp/0201633620>`_
1638    by John Lakos
1640 If you get some free time, and you haven't read them: do so, you might learn
1641 something.