Skip to content

Contributing: Coding Standards

Jump to bottom
Zachary Vincze edited this page May 27, 2026 · 2 revisions

Coding Standards

rocCV optimizes for readable, reviewable code that compiles cleanly across all supported GPU targets. Two non-negotiables: clang-format must pass and builds must be warning-free.

clang-format

The repo ships a .clang-format file (Google base, customized). Format every file you touch before opening a PR.

# Format a single file in place
clang-format -i src/op_<name>.cpp

# Format everything (run from repo root)
find include src tests python -name '*.hpp' -o -name '*.cpp' -o -name '*.h' \
    | xargs clang-format -i

# Check without modifying (CI-style)
clang-format --dry-run --Werror src/op_<name>.cpp

Editor integration: enable format-on-save in your IDE. VS Code: install the C/C++ extension and set "editor.formatOnSave": true.

Key settings (from .clang-format):

Setting Value
Base style Google
Column limit 120
Indent width 4 spaces (no tabs)
Pointer alignment Left (int* p, not int *p)
Template declaration breaks Always

Don't fight the formatter. If output looks wrong, fix the code structure, not the config.

Zero-Warning Builds

The project builds with -Wall -Wextra (CMakeLists.txt:117). Your changes must not introduce warnings on any supported GPU target.

Before pushing:

cmake --build . --parallel 2>&1 | tee build.log
grep -E "warning:|error:" build.log    # should be empty

Common warning sources to avoid:

  • Unused parameters → mark with [[maybe_unused]] or remove
  • Sign mismatch in comparisons → use consistent integer types
  • Implicit narrowing conversions → cast explicitly with intent
  • Shadowed variables → rename
  • Unhandled enum cases in switch → add default: or cover all cases

If you genuinely need to suppress one warning, use #pragma clang diagnostic with a comment explaining why — but pushing the warning back through the code is almost always better.

C++ Conventions

  • Standard: C++20. Use concepts, ranges, designated initializers where they improve readability.
  • Headers: #pragma once, not include guards.
  • Namespacing:
    • Public API in namespace roccv
    • GPU kernels in namespace Kernels::Device
    • CPU kernels in namespace Kernels::Host
  • Include order: project headers grouped by directory (core/, kernels/, common/), separated from standard and third-party headers by blank lines. clang-format will sort within groups.
  • Templates: keep __global__ kernel templates header-only (instantiated by the launching .cpp).
  • auto: use when the type is obvious from the RHS or verbose without adding clarity; prefer explicit types in public APIs.
  • const correctness: mark methods const, parameters const T& for non-trivial types.

Comments

Default to writing no comments. Names should carry the meaning. Add a comment only when the why is non-obvious — a constraint, a workaround for specific hardware behavior, or an invariant a reader couldn't infer.

Doxygen blocks on public headers are the exception — they are the API contract. See Contributing: Writing a New Operator for the required format.

Avoid:

  • Comments that restate the code (// increment i)
  • TODO comments without a tracked issue
  • Commented-out code (delete it; git remembers)

Naming

Kind Style Example
Types, classes PascalCase TensorWrapper, BorderType
Functions, methods camelCase dispatchKernel, flipCode
Variables camelCase inputWrapper, flipType
Constants, macros UPPER_SNAKE CHECK_TENSOR_DEVICE, DATA_TYPE_U8
Enums eCamelCase prefix, UPPER_SNAKE values eDeviceType::GPU, eAxis::X
Files snake_case op_flip.cpp, flip_device.hpp

Error Handling

  • Throw roccv::Exception with an appropriate eStatusType — never raw exceptions or error codes.
  • Validate at the public boundary (operator() entry). Kernels assume preconditions hold.
  • Use the CHECK_* macros from include/common/validation_helpers.hpp — they format consistent messages.

Python Binding Conventions

  • Mirror C++ operator names: roccv::Flip → rocpycv.flip
  • pybind11 binding lives in python/src/operators/Op<Name>.cpp
  • Register via PyOp<Name>::Export(m) in python/src/main.cpp
  • Expose dtype/layout enums through pybind11 — don't duplicate them

Pre-Push Checklist

  • clang-format clean on every modified file
  • Build succeeds with -Wall -Wextra, zero new warnings
  • All tests still pass (ctest + pytest)
  • No commented-out code, no TODO without an issue link
  • Public APIs have Doxygen blocks

Next Steps

Clone this wiki locally