llnl/axom/cpp-style

Axom C++ Style & Naming

Use this skill when adding or editing C++ in src/axom/, src/tools/, and src/examples/.

Formatting (clang-format)

• Axom's CMake source root is src/, and the formatter config is src/.clang-format.
• The config is Google-derived, currently requires clang-format 19 from the build system, uses ColumnLimit: 100, and does not auto-sort includes.
• Prefer letting formatting be enforced by the build-system target instead of hand-formatting.

Run auto-format from an existing build directory configured from src/:

cmake --build <build_dir> --target style
# example:
cmake --build build-debug --target style

Useful narrower targets include clangformat_style, clangformat_check, and component variants such as core_clangformat_style.

File structure

• License header: Keep the existing copyright + SPDX block at the top of C++ files.
• Header guards: Use #pragma once for headers.
• Doxygen file header: Use a Doxygen file prologue with \file and \brief.
• Namespaces: Prefer C++17 nested namespace syntax, e.g. namespace axom::slam { ... }.
• Namespace closing comment: Close with } // namespace axom::slam (match the opened namespace).
• Trailing newline: Ensure each file ends with a newline.

Includes

src/.clang-format has SortIncludes: false, so keep the project’s existing conventions:

• In a .cpp, include the corresponding header first (e.g., #include "axom/foo.hpp").
• Include axom/config.hpp before any Axom headers when a source file needs build configuration macros.
• Group includes with blank lines in this order: same Axom component, other Axom/project headers, TPL headers, C/C++ standard library, then system headers.
• Don’t churn includes solely to “sort” them; keep diffs minimal and consistent.
• Use // clang-format off / // clang-format on only for tightly controlled formatting blocks (e.g., initializer tables).

Naming conventions (as used in src/axom)

• When editing existing files, follow the naming conventions already used in that file for consistency.
• When creating new files under src/axom/<component>/, follow the naming style already used in that component directory.
• Namespaces: axom at the root; submodules use lowercase names such as axom::slam.
• Types (class, struct, enum class, using aliases): mixed/Pascal case (e.g., GeometryOperator).
• Functions/methods: camelCase (e.g., defineAndParse, findMeshFilePath).
• Local variables / parameters: snake_case/pot-hole (e.g., input_file_path, restart_cycle).
• Non-static data members: m_ plus snake_case (e.g., m_foo, m_use_warm_start).
• Static data members / file-scope statics: s_ plus snake_case (e.g., s_default_allocator).
• Macros / compile options: SCREAMING_SNAKE_CASE (e.g., AXOM_ENABLE_MPI, AXOM_DEBUG_PARAM).
• Enumeration values: Initial capital, with underscores between words when needed (e.g., Num_Orange_Types).
• Constants: SCREAMING_SNAKE_CASE for API constants; snake_case for local constexpr values.

Comments & documentation

• Prefer Doxygen-style docstrings for public APIs:
• \brief for summary
• \param[in] / \param[in,out] for parameters
• \tparam for template parameters
• Use /// for short Doxygen comments on declarations when a full block is overkill.