Skip to main content

Code Style

This page summarizes the code style currently used in the repository.

Naming​

  • Types, classes, structs, enum types, and member functions use PascalCase.
class Logger
{
 public:
  static void Init();
};
  • Local variables, function parameters, and data members use snake_case. Data members end with _.
static inline bool initialized_ = false;
  • Macros, error codes, log macros, and enum values stay uppercase.
#define ASSERT(arg) ...
#define XR_LOG_INFO(fmt, ...)

enum class ErrorCode : int8_t
{
  OK = 0,
  BUSY = -15,
  OUT_OF_RANGE = -17
};

Namespaces and Type Aliases​

  • Namespaces use Allman style, with an end comment retained.
namespace LibXR
{
}

}  // namespace LibXR
  • Prefer using for type aliases. Existing typedef declarations stay as they are.
using Callback = LibXR::Callback<uint32_t>;
typedef RBTree<uint32_t>::Node<Block>* TopicHandle;

File Organization​

  • In .cpp files, include the corresponding header first, then system headers, then project headers.
#include "async.hpp"

#include "libxr_def.hpp"
#include "thread.hpp"
  • Keep existing include order in headers. Do not reorder includes just for cleanup.
#include "app_framework.hpp"
#include "async.hpp"
#include "database.hpp"
  • Headers use #pragma once.
#pragma once

Layout​

  • Use Allman brace style.
class Thread
{
 public:
  enum class Priority : uint8_t
  {
    IDLE,
    LOW,
    MEDIUM
  };
};

  • Line breaking and wrapping follow the repository .clang-format; the current base is Google with ColumnLimit = 90.

  • Existing local spacing and blank lines may be kept where they improve readability.

  • Access specifiers are not indented further. Members are indented two spaces relative to the class body.

class Logger
{
 public:
  static void Init();

 private:
  static inline bool initialized_ = false;
};

Declarations and Definitions​

  • Short functions may be defined inline in the class body. Longer functions stay expanded.
~LockGuard() { mutex_.Unlock(); }

static void Sleep(uint32_t milliseconds);
  • constexpr, static constexpr, and static inline follow the existing style.
static constexpr size_t LIBXR_CACHE_LINE_SIZE = (sizeof(void*) == 8) ? 64 : 32;
static inline bool initialized_ = false;
  • explicit, operator, and [[nodiscard]] use their normal declaration positions.
explicit DatabaseRawSequential(Flash& flash, size_t max_buffer_size = 256);
[[nodiscard]] ErrorCode TryLock();
operator uint64_t() const;
  • Pointer and reference spacing follows the local file style. The repository contains both const char* and const char *; do not widen a diff just to unify them.

Comments​

  • Public headers continue to use the existing Doxygen style.
/**
 * @brief Publish a log message
 * @param level Log level
 * @param file Source file name
 */

  • Comments describe semantics, parameters, and boundary conditions. Do not record trial-and-error history.

  • Public header comments are often bilingual. New interfaces should follow the style already used in the surrounding file.

  • Simple local notes use short line comments.

// create thread
int ans = pthread_create(&this->thread_handle_, &attr, ThreadBlock::Port, block);

Macros and Exceptions​

  • Keep low-level helper macros in their existing macro form.
#define UNUSED(_x) ((void)(_x))
#define CONTAINER_OF(ptr, type, member) \
  ((type*)((char*)(ptr) - OFFSET_OF(type, member)))  // NOLINT
  • Apply NOLINT only at the exact location that needs it.
// NOLINTNEXTLINE
static void Publish(LogLevel level, const char* file, uint32_t line, const char* fmt,
                    ...);
  • Conditional compilation stays explicit.
#if defined(LIBXR_SYSTEM_Linux) || defined(LIBXR_SYSTEM_Webots)
#include "linux_shared_topic.hpp"
#endif
  • Keep extern "C", attributes, and platform macros in the existing direct style.
extern "C" __attribute__((weak)) void vApplicationStackOverflowHook(...);

Test Code​

  • Code under test/ may be more direct than public headers. Local macros, array literals, and compact test-driver code are acceptable there.
#define TEST_STEP(_arg)                                \
  do                                                   \
  {                                                    \
    test_name = _arg;                                  \
  } while (0)
  • Naming, brace style, and basic layout still follow the same conventions as the main code.

clang-format​

  • The repository has a root .clang-format.
  • CI uses clang-format 21.1.8. The check entry is:
tools/format_driver_src.sh --check
  • The current script checks C/C++ source files under driver/ and src/.