desktop-team-doc 0.1.0

package/content/rules/cpp.mdc

@@ -0,0 +1,135 @@
+---
+alwaysApply: true
+---
+# C++ Coding Standards
+
+*Last Updated: 2025-10-14*
+
+This document outlines the C++ coding standards for the Desktop Team, specifically for BIAS_ONE and related C++ projects.
+
+## Formatting
+
+* All C++ code formatting MUST strictly adhere to the `.clang-format` configuration file located in the project root.
+* Ensure any generated or modified code would pass checks using this `.clang-format` file.
+* A reference `.clang-format` configuration is available at [`.clang-format`](./.clang-format) in this directory.
+
+### Key Formatting Rules (from `.clang-format`)
+
+* **Indentation**: 4 spaces (not tabs)
+* **Line Length**: Maximum 100 characters
+* **Brace Placement**:
+  * Functions, classes, structs, enums, unions: Opening brace on separate line
+  * Control statements (if, for, while, etc.): Opening brace on same line
+  * Lambda bodies: Opening brace on separate line
+* **Trailing Whitespace**: None allowed
+* **Empty Lines**: No indentation on empty lines; max 2 consecutive empty lines
+* **Pointer Alignment**: Right-aligned (e.g., `int *ptr`, not `int* ptr`)
+
+**Note**: These C++ formatting rules differ from team-wide defaults. When conflicts arise, `.clang-format` is the source of truth for C++ code.
+
+## Naming Rules
+
+### General Naming
+
+* Names must be descriptive and clear; avoid unclear abbreviations.
+* Commonly recognized abbreviations (e.g., `i`, `T`, `DNS`, `LSTM`) are acceptable.
+* Use full capitalization for acronyms within camelCase names (e.g., `startRPC`, `dnsEntryCount`, not `startRpc`).
+* Template parameter names follow type naming (UpperCamelCase) if they are types, or variable naming (lowerCamelCase) if they are non-types.
+* Namespace names are lowercase with underscores as separators (e.g., `util_embedded_store`).
+
+### File Names
+
+* Use UpperCamelCase (e.g., `PresetManager`).
+* Header files use `.hpp`, source files use `.cpp`.
+
+### Type Names
+
+* Use UpperCamelCase without underscores for classes, structs, type aliases (`using`/`typedef`), enums, and type template parameters (e.g., `UrlTable`, `PropertiesMap`, `UrlTableErrors`).
+
+### Variable Names
+
+* Use lowerCamelCase.
+* Class member non-static variables MUST end with an underscore (`_`) (e.g., `dataMember_`, `pool_`).
+* Struct member variables MUST NOT end with an underscore (e.g., `dataMember`).
+* Do not encode type in variable names (e.g., avoid `strDeviceName`, `pStr`).
+
+### Constant Names
+
+* Prefix with `k` and use CamelCase (e.g., `kDaysInAWeek`, `kAndroid8_0_0`). Underscores only if needed for readability within the name itself.
+
+### Enum Names
+
+* Use scoped enums: `enum class EnumName { ... };`.
+* Enum type name (`EnumName`): UpperCamelCase.
+* Enum values: lowerCamelCase (like variables) (e.g., `errorOutOfMemory`).
+
+## Functions and Methods
+
+* Names use lowerCamelCase (e.g., `doFunc`).
+* Opening `{` and closing `}` braces must be on separate lines (enforced by `.clang-format`).
+* Each function should perform a single, clearly defined task. Refactor if the name isn't descriptive.
+* Parameter Order: Input (`const &`) first, then modification (`&`), then output (`&`).
+* Prefer returning values (using `std::tuple`, structs, etc.) over output parameters.
+
+**Example**:
+
+```cpp
+auto processData(const std::string &input, int &counter) -> std::vector<int>
+{
+    // Function body
+    counter++;
+    return result;
+}
+```
+
+## Lambda Functions
+
+* Prefer explicit capture lists (e.g., `[x, &y, z]`) over default capture (`[=]`, `[&]`).
+* Use `[=]` capture only when necessary.
+* Declare lambdas locally within the function if used only there. Consider making them private class methods if reused.
+
+## `auto` Usage
+
+### Variables
+
+* Prefer `auto` for declarations, especially with complex/long types (e.g., `auto message = std::string{};`, `constexpr auto kEnable...`).
+* Exception for C-style API init: Declare with explicit type first (`int value; initValue(&value);`), or use an immediately-invoked lambda for const-correct initialization: `auto const value = []{ int v; initValue(&v); return v; }();`.
+
+### Function Return Types
+
+* Use `auto -> TrailingReturnType;` (e.g., `auto doFunction() -> std::string;`).
+* Exception for Return Types: Short `inline`, `constexpr`, or `consteval` functions can use plain `auto` deduction if the return type is obvious (e.g., `constexpr auto plusOne(int value)`).
+* Use `decltype(auto)` sparingly, primarily for perfect forwarding or preserving reference types in getters (e.g., `auto& getProperty() { return property_; }`).
+
+## Class Structure
+
+### Order of declarations
+
+1. `public:` types (enums, structs), static methods, constructors/destructor/operators, public methods.
+2. `public:` member variables (use sparingly).
+3. `protected:` (use minimally).
+4. `private:` methods.
+5. `private:` member variables.
+
+* Use separate `public:` and `private:` sections for methods vs. member variables for clarity.
+
+## Pointers and References
+
+* Use smart pointers (`std::unique_ptr`, `std::shared_ptr`) to manage ownership instead of raw pointers.
+* Prefer references (`const T&`, `T&`) over raw pointers (`T*`).
+* Use raw pointers only when:
+  * Rebinding (pointing to different objects) is needed.
+  * `nullptr` representation is needed.
+  * Interfacing with C APIs or legacy code requires them.
+
+## Miscellaneous
+
+* **Header Guards**: Use `#pragma once`.
+
+## Commenting Policy
+
+See [Team-wide Coding Conventions](./team-wide.md#commenting-policy) for the team's commenting policy which applies to all languages including C++.
+
+## Related Resources
+
+* [Team-wide Coding Conventions](./team-wide.md) - Universal coding standards across all languages