weaseldb/style.md

WeaselDB C++ Style Guide

This document describes the C++ coding style used in the WeaselDB project. These conventions ensure consistency, readability, and maintainability across the codebase.

Table of Contents

1. General Principles
2. Naming Conventions
3. File Organization
4. Code Structure
5. Memory Management
6. Error Handling
7. Documentation
8. Testing

---

General Principles

Language Standard

• C++20 is the target standard
• Use modern C++ features: RAII, move semantics, constexpr, concepts where appropriate
• Prefer standard library containers and algorithms over custom implementations

Data Types

• Almost always signed - prefer int, int64_t, size_t over unsigned types except for:
  • Bit manipulation operations
  • Interfacing with APIs that require unsigned types
  • Memory sizes where overflow is impossible (size_t, uint32_t for arena block sizes)
  • Where defined unsigned overflow behavior (wraparound) is intentional and desired
• Almost always auto - let the compiler deduce types except when:
  • The type is not obvious from context (prefer explicit for clarity)
  • Specific type requirements matter (numeric conversions, template parameters)
  • Interface contracts need explicit types (public APIs, function signatures)
• Prefer uninitialized memory to default initialization when using before initializing would be an error
  • Valgrind will catch uninitialized memory usage bugs
  • Avoid hiding logic errors with unnecessary zero-initialization
  • Default initialization can mask bugs and hurt performance
• Floating point is for metrics only - avoid float/double in core data structures and algorithms
  • Use for performance measurements, statistics, and monitoring data
  • Never use for counts, sizes, or business logic

Performance Focus

• Performance-first design - optimize for the hot path
• Simple is fast - find exactly what's necessary, strip away everything else
• Complexity must be justified with benchmarks - measure performance impact before adding complexity
• Strive for 0% CPU usage when idle - avoid polling, busy waiting, or unnecessary background activity
• Use inline functions for performance-critical code (e.g., allocate_raw)
• Zero-copy operations with std::string_view over string copying
• Arena allocation for efficient memory management (see Memory Management section for details)

Complexity Control

• Encapsulation is the main tool for controlling complexity
• Header files define the interface - they are the contract with users of your code
• Headers should be complete - include everything needed to use the interface effectively:
  • Usage examples in comments
  • Preconditions and postconditions
  • Thread safety guarantees
  • Performance characteristics
  • Ownership and lifetime semantics
• Do not rely on undocumented interface properties - if it's not in the header, don't depend on it

---

Naming Conventions

Variables and Functions

• snake_case for all variables, functions, and member functions

size_t used_bytes() const;
void add_block(size_t size);
uint32_t initial_block_size_;

Structs

• PascalCase for struct names
• Always use struct - eliminates debates about complexity and maintains consistency
• Public members first, private after - puts the interface users care about at the top, implementation details below
• Full encapsulation still applies - use private: sections to hide implementation details and maintain deep, capable classes
• The struct keyword doesn't mean shallow design - it means interface-first organization for human readers

struct ArenaAllocator {
  // Public interface first
  explicit ArenaAllocator(size_t initial_size = 1024);
  void* allocate_raw(size_t size);

private:
  // Private members after
  uint32_t initial_block_size_;
  Block* current_block_;
};

Enums

• PascalCase for enum class names
• PascalCase for enum values (not SCREAMING_SNAKE_CASE)

enum class Type {
  PointRead,
  RangeRead
};

enum class ParseState {
  Root,
  PreconditionsArray,
  OperationObject
};

Constants and Macros

• snake_case for constants
• Avoid macros when possible; prefer constexpr variables

static const WeaselJsonCallbacks json_callbacks;

Member Variables

• Trailing underscore for private member variables

private:
  uint32_t initial_block_size_;
  Block *current_block_;

Template Parameters

• PascalCase for template type parameters

template <typename T, typename... Args>
template <typename T> struct rebind { using type = T*; };

---

File Organization

Include Organization

• Use #pragma once instead of include guards
• Never using namespace std - always use fully qualified names for clarity and safety
• Include order (applies to both headers and source files):
  1. Corresponding header file (for .cpp files only)
  2. Standard library headers (alphabetical)
  3. Third-party library headers
  4. Project headers

#pragma once

#include <algorithm>
#include <cstddef>
#include <cstdint>
#include <memory>
#include <string_view>

#include <simdutf.h>
#include <weaseljson/weaseljson.h>

#include "arena_allocator.hpp"
#include "commit_request.hpp"

// Never this:
// using namespace std;

// Always this:
std::vector<int> data;
std::unique_ptr<Parser> parser;

---

Code Structure

Struct Design

• Move-only semantics for resource-owning structs
• Explicit constructors to prevent implicit conversions
• Delete copy operations when inappropriate

struct ArenaAllocator {
  explicit ArenaAllocator(size_t initial_size = 1024);

  // Copy construction is not allowed
  ArenaAllocator(const ArenaAllocator &) = delete;
  ArenaAllocator &operator=(const ArenaAllocator &) = delete;

  // Move semantics
  ArenaAllocator(ArenaAllocator &&other) noexcept;
  ArenaAllocator &operator=(ArenaAllocator &&other) noexcept;

private:
  uint32_t initial_block_size_;
  Block *current_block_;
};

Function Design

• Const correctness - mark methods const when appropriate
• Parameter passing:
  • Pass by value for types ≤ 16 bytes (int, pointers, string_view, small structs)
  • Pass by const reference for types > 16 bytes (containers, large objects)
• Return by value for small types (≤ 16 bytes), string_view for zero-copy over strings
• noexcept specification for move operations and non-throwing functions

std::span<const Operation> operations() const { return operations_; }
void process_data(std::string_view data);  // ≤ 16 bytes, pass by value
void process_request(const CommitRequest& req);  // > 16 bytes, pass by reference
ArenaAllocator(ArenaAllocator &&other) noexcept;

Template Usage

• Template constraints using static_assert for better error messages
• SFINAE or concepts for template specialization

Factory Patterns & Ownership

• Static factory methods for complex construction requiring shared ownership
• Friend-based factories for access control when constructor should be private
• Ownership guidelines:
  • unique_ptr for exclusive ownership (most common case)
  • shared_ptr only when multiple owners need concurrent access to same object
  • Factory methods return appropriate smart pointer type based on ownership needs

// Shared ownership - multiple components need concurrent access
auto server = Server::create(config, handler);  // Returns shared_ptr

// Exclusive ownership - single owner, transfer via move
auto connection = Connection::createForServer(...);  // Returns unique_ptr

// Friend-based factory for access control
struct Connection {
  void appendMessage(std::string_view data);
private:
  Connection(/* args */);  // Private constructor
  friend struct Server;   // Only Server can construct
};

Control Flow

• Early returns to reduce nesting
• Range-based for loops when possible

if (size == 0) {
  return nullptr;
}

for (auto &precondition : preconditions_) {
  // ...
}

---

Memory Management

Ownership & Allocation

• Arena allocators for request-scoped memory with STL allocator adapters (provides ~1ns allocation vs ~20-270ns for malloc)
• String views pointing to arena-allocated memory for zero-copy operations
• STL containers with arena allocators require default construction after arena reset - clear() is not sufficient

// STL containers with arena allocators - correct reset pattern
std::vector<Operation, ArenaStlAllocator<Operation>> operations(arena_alloc);
// ... use container ...
operations = {};  // Default construct - clear() won't work correctly
arena.reset();  // Reset arena memory

Resource Management

• RAII everywhere - constructors acquire, destructors release
• Move semantics for efficient resource transfer
• Explicit cleanup methods where appropriate

~ArenaAllocator() {
  while (current_block_) {
    Block *prev = current_block_->prev;
    std::free(current_block_);
    current_block_ = prev;
  }
}

---

Error Handling

Error Classification & Response

• Expected errors (invalid input, timeouts): Return error codes for programmatic handling
• System failures (malloc fail, socket fail): Abort immediately with error message
• Programming errors (precondition violations, assertions): Abort immediately

Error Contract Design

• Error codes are the API contract - use enums for programmatic decisions
• Error messages are human-readable only - never parse message strings
• Consistent error boundaries - each component defines what it can/cannot recover from
• Interface precondition violations are undefined behavior - acceptable to skip checks for performance in hot paths

enum class ParseResult { Success, InvalidJson, MissingField };

// System failure - abort immediately
void* memory = malloc(size);
if (!memory) {
    std::fprintf(stderr, "ArenaAllocator: Memory allocation failed\n");
    std::abort();
}
// ... use memory, eventually free it

// Programming error - precondition violation (may be omitted for performance)
assert(ptr != nullptr && "Precondition violated: pointer must be non-null");

Assertions

• Programming error detection using standard assert() macro
• Assertion behavior follows C++ standards:
  • Debug builds: Assertions active (undefined NDEBUG)
  • Release builds: Assertions removed (defined NDEBUG)
• Test targets override: Use -UNDEBUG to force assertions active in all builds
• Static assertions for compile-time validation (always active)

Usage guidelines:

• Use for programming errors: null checks, precondition validation, invariants
• Don't use for expected runtime errors: use return codes instead

// Good: Programming error checks
assert(current_block_ && "realloc called with non-null ptr but no current block");
assert(size > 0 && "Cannot allocate zero bytes");

// Good: Compile-time validation (always enabled)
static_assert(std::is_trivially_destructible_v<T>, "Arena requires trivially destructible types");

// Bad: Don't use assert for expected runtime errors
// assert(file_exists(path));  // File might legitimately not exist - use return code instead

---

Documentation

Doxygen Style

• / for struct and public method documentation
• @brief for short descriptions
• @param and @return for function parameters
• @note for important implementation notes
• @warning for critical usage warnings

/**
 * @brief Type-safe version of realloc_raw for arrays of type T.
 * @param ptr Pointer to the existing allocation
 * @param old_size Size in number of T objects
 * @param new_size Desired new size in number of T objects
 * @return Pointer to reallocated memory
 * @note Prints error to stderr and calls std::abort() if allocation fails
 */
template <typename T>
T *realloc(T *ptr, uint32_t old_size, uint32_t new_size);

Code Comments

• Explain why, not what - code should be self-documenting
• Performance notes for optimization decisions
• Thread safety and ownership semantics

// Uses O(1) accumulated counters for fast retrieval
size_t total_allocated() const;

// Only Server can create connections - no public constructor
Connection(struct sockaddr_storage addr, int fd, int64_t id,
           ConnectionHandler *handler, std::weak_ptr<Server> server);

---

Testing

Test Framework

• doctest for unit testing
• TEST_CASE and SUBCASE for test organization
• CHECK for assertions (non-terminating)
• REQUIRE for critical assertions (terminating)

Test Structure

• Descriptive test names explaining the scenario
• SUBCASE for related test variations
• Fresh instances for each test to avoid state contamination

TEST_CASE("ArenaAllocator basic allocation") {
  ArenaAllocator arena;

  SUBCASE("allocate zero bytes returns nullptr") {
    void *ptr = arena.allocate_raw(0);
    CHECK(ptr == nullptr);
  }

  SUBCASE("allocate single byte") {
    void *ptr = arena.allocate_raw(1);
    CHECK(ptr != nullptr);
    CHECK(arena.used_bytes() >= 1);
  }
}

Test Design Principles

• Prefer testing through public interfaces - focus on observable behavior rather than implementation details
• Test the contract, not the implementation - validate what the API promises to deliver
• Avoid testing private methods directly - if private functionality needs testing, consider if it should be public or extracted
• Both integration and unit tests - test components in isolation and working together
• Prefer fakes to mocks - use real implementations for internal components, fake external dependencies
• Always enable assertions in tests - use -UNDEBUG pattern to ensure assertions are checked (see Build Integration section)

// Good: Testing through public API
TEST_CASE("Server accepts connections") {
  auto config = Config::defaultConfig();
  auto handler = std::make_unique<TestHandler>();
  auto server = Server::create(config, std::move(handler));

  // Test observable behavior - server can accept connections
  auto result = connectToServer(server->getPort());
  CHECK(result.connected);
}

// Avoid: Testing internal implementation details
// TEST_CASE("Server creates epoll instance") { /* implementation detail */ }

Test Synchronization (Authoritative Rules)

• ABSOLUTELY NEVER use timeouts (sleep_for, wait_for, etc.)
• Deterministic synchronization only:
  • Blocking I/O (naturally waits for completion)
  • condition_variable.wait() without timeout
  • std::latch, std::barrier, futures/promises
• Force concurrent execution using std::latch to synchronize thread startup
• Tests should pass or hang - no flaky timeout behavior

// BAD: Race likely over before threads start
std::atomic<int> counter{0};
for (int i = 0; i < 4; ++i) {
  threads.emplace_back([&]() { counter++; }); // Probably sequential
}

// GOOD: Force threads to race simultaneously
std::atomic<int> counter{0};
std::latch start_latch{4};
for (int i = 0; i < 4; ++i) {
  threads.emplace_back([&]() {
    start_latch.count_down_and_wait(); // All threads start together
    counter++; // Now they actually race
  });
}

---

Build Integration

Build Configuration

# Debug: assertions on, optimizations off
cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Debug -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

# Release: assertions off, optimizations on
cmake .. -G Ninja -DCMAKE_BUILD_TYPE=Release -DCMAKE_EXPORT_COMPILE_COMMANDS=ON

Test Target Pattern:

• Production targets follow build type (assertions off in Release)
• Test targets use -UNDEBUG to force assertions on in all builds
• Ensures consistent test validation regardless of build type

# Test target with assertions always enabled
add_executable(test_example tests/test_example.cpp src/example.cpp)
target_link_libraries(test_example doctest::doctest)
target_compile_options(test_example PRIVATE -UNDEBUG)  # Always enable assertions

# Production target follows build type
add_executable(example src/example.cpp src/main.cpp)
# No -UNDEBUG → assertions disabled in Release, enabled in Debug

Code Generation

• gperf for perfect hash table generation
• Build-time generation of token lookup tables
• Include generated headers from build directory

---

Style Enforcement

Consistency

• Follow existing patterns in the codebase
• Use the same style for similar constructs
• Maintain consistency within each translation unit

Tools

• clang-format configuration (when available)
• Static analysis tools for code quality
• Address sanitizer for memory safety testing

This style guide reflects the existing codebase patterns and should be followed for all new code contributions to maintain consistency and readability.