198 lines · plain
1.. _CodingGuidelines:2 3========================4libc++ Coding Guidelines5========================6 7.. contents::8 :local:9 10Use ``__ugly_names`` for implementation details11===============================================12 13Libc++ uses ``__ugly_names`` or ``_UglyNames`` for implementation details. These names are reserved for implementations,14so users may not use them in their own applications. When using a name like ``T``, a user may have defined a macro that15changes the meaning of ``T``. By using ``__ugly_names`` we avoid that problem.16 17This is partially enforced by the clang-tidy check ``readability-identifier-naming`` and18``libcxx/test/libcxx/system_reserved_names.gen.py``.19 20Don't use argument-dependent lookup unless required by the standard21===================================================================22 23Unqualified function calls are susceptible to24`argument-dependent lookup (ADL) <https://en.cppreference.com/w/cpp/language/adl>`_. This means calling25``move(UserType)`` might not call ``std::move``. Therefore, function calls must use qualified names to avoid ADL. Some26functions in the standard library `require ADL usage <http://eel.is/c++draft/contents#3>`_. Names of classes, variables,27concepts, and type aliases are not subject to ADL. They don't need to be qualified.28 29Function overloading also applies to operators. Using ``&user_object`` may call a user-defined ``operator&``. Use30``std::addressof`` instead. Similarly, to avoid invoking a user-defined ``operator,``, make sure to cast the result to31``void`` when using the ``,`` or avoid it in the first place. For example:32 33.. code-block:: cpp34 35 for (; __first1 != __last1; ++__first1, (void)++__first2) {36 ...37 }38 39This is mostly enforced by the clang-tidy check ``libcpp-robust-against-adl``.40 41Avoid including public headers42==============================43 44libc++ uses implementation-detail headers for most code. These are in a directory that starts with two underscores45(e.g. ``<__type_traits/decay.h>``). These detail headers are significantly smaller than their public counterparts.46This reduces the amount of code that is included in a single public header, which reduces compile times.47 48Add ``_LIBCPP_HIDE_FROM_ABI`` unless you know better49====================================================50 51``_LIBCPP_HIDE_FROM_ABI`` should be on every function in the library unless there is a reason not to do so. The main52reason not to add ``_LIBCPP_HIDE_FROM_ABI`` is if a function is exported from the libc++ built library. In that case the53function should be marked with ``_LIBCPP_EXPORTED_FROM_ABI``. Virtual functions should be marked with54``_LIBCPP_HIDE_FROM_ABI_VIRTUAL`` instead.55 56This is mostly enforced by the clang-tidy checks ``libcpp-hide-from-abi`` and ``libcpp-avoid-abi-tag-on-virtual``.57 58Define configuration macros to 0 or 159=====================================60 61Macros should usually be defined in all configurations, instead of defining them when they're enabled and leaving them62undefined otherwise. For example, use63 64.. code-block:: cpp65 66 #if SOMETHING67 # define _LIBCPP_SOMETHING_ENABLED 168 #else69 # define _LIBCPP_SOMETHING_ENABLED 070 #endif71 72and then check for ``#if _LIBCPP_SOMETHING_ENABLED`` instead of73 74.. code-block:: cpp75 76 #if SOMETHING77 # define _LIBCPP_SOMETHING_ENABLED78 #endif79 80and then checking for ``#ifdef _LIBCPP_SOMETHING_ENABLED``.81 82This makes it significantly easier to catch missing includes: Clang and GCC with ``-Wundef`` enabled will warn83when using an undefined macro inside an ``#if`` statement. Some macros in libc++ don't use this style yet,84so this guideline only applies when introducing a new macro.85 86This is partially enforced by the clang-tidy check ``libcpp-internal-ftms``.87 88Use ``_LIBCPP_STD_VER``89=======================90 91libc++ defines the macro ``_LIBCPP_STD_VER`` for the different libc++ dialects. This should be used instead of92``__cplusplus``.93 94This is mostly enforced by the clang-tidy check ``libcpp-cpp-version-check``.95 96Use ``__ugly__`` spellings of vendor attributes97===============================================98 99Vendor attributes should always be ``__uglified__`` to avoid naming clashes with user-defined macros. For gnu-style100attributes this takes the form ``__attribute__((__foo__))``. C++11-style attributes look like ``[[_Clang::__foo__]]`` or101``[[__gnu__::__foo__]]`` for Clang or GCC attributes respectively. Clang and GCC also support standard attributes in102earlier language dialects than they were introduced. These should be spelled as ``[[__foo__]]``. MSVC currently doesn't103provide alternative spellings for their attributes, so these should be avoided if at all possible.104 105This is enforced by the clang-tidy check ``libcpp-uglify-attributes``.106 107Use C++11 extensions in C++03 code if they simplify the code108============================================================109 110libc++ supports the C++98/03 mode only with the Clang compiler. Clang provides many C++11 features111in C++03, making it possible to write a lot of code in a simpler way than if we were restricted to C++03 features.112Some use of extensions is even mandatory, since libc++ supports move semantics in C++03.113 114Use ``using`` aliases instead of ``typedef``115============================================116 117``using`` aliases are generally easier to read and support templates. Some code in libc++ uses ``typedef`` for118historical reasons.119 120Write SFINAE with ``requires`` clauses in C++20-only code121=========================================================122 123``requires`` clauses can be significantly easier to read than ``enable_if`` and friends in some cases, since concepts124subsume other concepts. This means that overloads based on traits can be written without negating more general cases.125They also show intent better.126 127Write ``enable_if`` as ``enable_if_t<condition, int> = 0``128==========================================================129 130The form ``enable_if_t<condition, int> = 0`` is the only one that works in every language mode and for overload sets131using the same template arguments otherwise. If the code must work in C++11 or C++03, the libc++-internal alias132``__enable_if_t`` can be used instead.133 134Prefer alias templates over class templates135===========================================136 137Alias templates are much more lightweight than class templates, since they don't require new instantiations for138different types. If the only member of a class is an alias, like in type traits, alias templates should be used if139possible. They do force more eager evaluation though, which can be a problem in some cases.140 141Apply ``[[nodiscard]]`` where relevant142======================================143 144Libc++ adds ``[[nodiscard]]`` whenever relevant to catch potential bugs. The standards committee has decided to _not_145have a recommended practice where to put them, so libc++ applies it whenever it makes sense to catch potential bugs.146 147``[[nodiscard]]`` should be applied to functions148 149- where discarding the return value is most likely a correctness issue. For example a locking constructor in150 ``unique_lock``.151 152- where discarding the return value likely points to the user wanting to do something different. For example153 ``vector::empty()``, which probably should have been ``vector::clear()``.154 155 This can help spotting bugs easily which otherwise may take a very long time to find.156 157- which return a constant. For example ``numeric_limits::min()``.158- which only observe a value. For example ``string::size()``.159 160 Code that discards values from these kinds of functions is dead code. It can either be removed, or the programmer161 meant to do something different.162 163- where discarding the value is most likely a misuse of the function. For example ``std::find(first, last, val)``.164 165 This protects programmers from assuming too much about how the internals of a function work, making code more robust166 in the presence of future optimizations.167 168Applications of ``[[nodiscard]]`` are code like any other code, so we aim to test them on public interfaces. This can be169done with a ``.verify.cpp`` test. Many examples are available. Just look for tests with the suffix170``.nodiscard.verify.cpp``.171 172Don't use public API names for symbols on the ABI boundary173==========================================================174 175Most functions in libc++ are defined in headers either as templates or as ``inline`` functions. However, we sometimes176need or want to define functions in the built library. Symbols that are declared in the headers and defined in the177built library become part of the ABI of libc++, which must be preserved for backwards compatibility. This means that178we can't easily remove or rename such symbols except in special cases.179 180When adding a symbol to the built library, make sure not to use a public name directly. Instead, define a181``_LIBCPP_HIDE_FROM_ABI`` function in the headers with the public name and have it call a private function in the built182library. This approach makes it easier to make changes to libc++ like move something from the built library to the183headers (which is sometimes required for ``constexpr`` support).184 185When defining a function at the ABI boundary, it can also be useful to consider which attributes (like ``[[gnu::pure]]``186and ``[[clang::noescape]]``) can be added to the function to improve the compiler's ability to optimize.187 188Library-internal type aliases should be annotated with ``_LIBCPP_NODEBUG``189==========================================================================190 191Libc++ has lots of internal type aliases. Accumulated, these can result in significant amounts of debug information that192users generally don't care about, since users don't try to debug standard library facilities in most cases. For that193reason, all library-internal type aliases that aren't function-local should be annotated with ``_LIBCPP_NODEBUG`` to194prevent compilers from generating said debug information. Aliases inside type traits (i.e. aliases named ``type``)195should be annotated for the same reason.196 197This is enforced by the clang-tidy check ``libcpp-nodebug-on-aliases``.198