project_6/cccl_upstream/.agent/skills/cccl-style/references/common.md

Common CCCL Style Guidance

Apply this guidance across CCCL unless a path-specific style reference says otherwise.

Naming Style

• Macros: macro style, e.g. MY_MACRO.
• Template parameters: PascalCase, e.g. MyParameter.
• All other symbols: snake style, e.g. my_variable. The one exception is the CUB public API, which uses PascalCase.

Variables

• All variables that are not modified must use const. This includes variables initialized by casts (static_cast, reinterpret_cast, bit_cast), function return values, and loop-invariant computations.
• All variables that can be evaluated at compile-time must use constexpr.
• All constexpr variables at namespace/global scope must use inline, including variable templates.
• Consider using plural names for array, span, list, e.g. int values[4] instead of int value[4].
• Use uniform initialization for class constructors (not enforced to builtin types) and compile-time conversions, e.g. constexpr auto x = int{sizeof(float)};.

Headers

• Files must include all headers related to the symbols that they are using.
• Relying on transitive header inclusion is not allowed.
• Unneeded headers must be removed.
• All headers must have the correct license. This also applies to source files.
• All header inclusions must use the syntax <header>.
• Use forward declaration, namely __fwd/header.h or direct type declaration, when possible instead of including the implementation header.
• Headers should be the most precise available, e.g. #include <cuda/std/__type_traits/is_array.h>.
• Do not include headers in cuda/std/__cccl/ directly; they are provided by __config or the prologue/epilogue mechanism.

Functions

• Functions must be marked _CCCL_HOST_API, _CCCL_DEVICE_API, _CCCL_HOST_DEVICE_API, _CCCL_TILE_API, or _CCCL_API.
• Non-template, non-constexpr functions must use inline.
• Most functions with a non-void return type should use [[nodiscard]]; functions with known side effects may be exceptions.
• Functions that do not throw exceptions must use noexcept.
• Use _CCCL_CONSTEVAL when the function can only be evaluated at compile time.
• Use C++20 concept macros instead of SFINAE, e.g. _CCCL_TEMPLATE(...) and _CCCL_REQUIRES(...).

Function Calls And Types

• In headers, apply global qualification where the subproject requires it:
  • libcudacxx and cudax require free function calls to be fully qualified from the global namespace, e.g. ::cuda::ceil_div(...).
  • CUB applies this rule only to calls to symbols under the ::cuda namespace hierarchy; otherwise follow existing CUB qualification style.
  • Thrust uses leading :: for many symbols under the ::cuda namespace hierarchy, but relies on ADL in many places and the blanket free-function qualification rule does not apply to those calls.
• For covered calls, this includes calls to functions defined in the same namespace, e.g. inside cuda::, call ::cuda::ceil_div(...), not ceil_div(...). This does not apply to (static) member functions of classes. The only exceptions for covered calls are functions that are supposed to be found through argument-dependent lookup (ADL), such as ::cuda::std::swap and ::cuda::std::get. Those functions can be called unqualified with a preceding using ::cuda::std::get;.
• This global-qualification rule does not apply to source files such as tests and benchmarks.
• In headers, apply type-name qualification where the subproject requires it:
  • libcudacxx and cudax require type names to be fully qualified except when they are already declared in the current namespace or an enclosing one. Outside those namespaces, fully qualify cuda::std and standard integer type aliases such as ::cuda::std::size_t.
  • CUB applies this rule only to type names under the ::cuda namespace hierarchy. Do not apply the libcudacxx/cudax blanket type-qualification rule to CUB namespaces or detail namespaces.
  • Thrust does not apply the libcudacxx/cudax blanket type-qualification rule. It uses leading :: for many ::cuda and ::cuda::std type names, but also uses Thrust namespace patterns; follow neighboring Thrust code.
• A local using declaration, e.g. using ::cuda::std::size_t;, is acceptable to avoid repetition within a function body.
• Static member functions of a class template inherit the class's namespace.

Comments

• Commented code without a description is not allowed.

General Guidelines

• The code must reuse cuda/ or cuda/std functionalities as much as possible, including macros.
• Try to use modern C++ as much as possible. The repository supports C++17 but many more recent functionalities have been backported with functions and macros.

Prevent Compiler Errors And Improve Compatibility

• Remove unused code, variables, functions, types, template parameters, headers, etc.
• Variables that are unsigned, or that can become unsigned after template instantiation, must not check for negative values directly. Use cuda::std::is_unsigned_v<T> ? false : (var < 0) instead.

Compiler Compatibility

• Protect host-only code with #if !_CCCL_COMPILER(NVRTC).