smith-cpp-style

name	smith-cpp-style
description	C++ coding style and naming conventions for Smith (primarily src/smith), including formatting via the CMake `style` target.

Smith C++ Style & Naming

Use this skill when adding or editing C++ in src/smith/ and examples/. Do not use this for tribol, mfem, or axom.

Formatting (clang-format)

• Smith uses repo-root .clang-format (Google-derived, ColumnLimit: 120, includes are not auto-sorted).
• Prefer letting formatting be enforced by the build-system target instead of hand-formatting.

Run auto-format (from an existing build directory):

cmake --build <build_dir> --target style
# example:
cmake --build build --target 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 /** ... */ block with @file and @brief.
• Namespaces: Prefer nested namespaces like namespace smith::input { ... }.
• Namespace closing comment: Close with } // namespace smith::input (match the opened namespace).
• Trailing newline: Ensure each file ends with a newline.

Includes

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

• In a .cpp, include the corresponding header first (e.g., #include "smith/foo.hpp").
• Include smith/smith_config.hpp before any Smith headers.
• Group includes with blank lines (typical grouping: C++ standard library, third-party, Smith 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/smith)

• Namespaces: smith at the root; submodules use smith::<module>.
• Types (class, struct, enum class, using aliases): PascalCase (e.g., SolidMechanicsContact).
• Functions/methods: camelCase (e.g., defineAndParse, findMeshFilePath).
• Local variables / parameters: snake_case (e.g., input_file_path, restart_cycle).
• Data members: snake_case_ trailing underscore (e.g., contact_, use_warm_start_).
• Macros / compile options: SCREAMING_SNAKE_CASE (e.g., MFEM_USE_MPI, SMITH_MARK_FUNCTION).
• Constants: prefer SCREAMING_SNAKE_CASE when it’s part of a type’s API (e.g., NUM_STATE_VARS); for small local constexpr values, use a descriptive name that reads well at the callsite.

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.