diff options
Diffstat (limited to 'archived/projt-launcher/docs/contributing/CODE_STYLE.md')
| -rw-r--r-- | archived/projt-launcher/docs/contributing/CODE_STYLE.md | 230 |
1 files changed, 230 insertions, 0 deletions
diff --git a/archived/projt-launcher/docs/contributing/CODE_STYLE.md b/archived/projt-launcher/docs/contributing/CODE_STYLE.md new file mode 100644 index 0000000000..b51725a92d --- /dev/null +++ b/archived/projt-launcher/docs/contributing/CODE_STYLE.md @@ -0,0 +1,230 @@ +# Code Style + +Formatting and coding standards for ProjT Launcher. + +--- + +## Formatting + +All C++ code must be formatted with clang-format before committing. + +```sh +clang-format -i path/to/file.cpp +``` + +CI will reject unformatted code. + +--- + +## C++ Standards + +### Modern C++ + +| Feature | Usage | +|---------|-------| +| `auto` | Only when type is obvious | +| `nullptr` | Always (never `NULL` or `0`) | +| `override` | Required on all overrides | +| `const` | Required for non-mutating methods | + +### Memory Management + +**Smart Pointers**: + +```cpp +// Good +auto obj = std::make_unique<MyClass>(); + +// Bad - raw pointer ownership +MyClass* obj = new MyClass(); +``` + +**Qt Parent Ownership**: + +```cpp +// Good - Qt manages lifetime +new QButton(this); +``` + +### Error Handling + +- Avoid exceptions +- Use `std::optional` for missing values +- Use `std::expected` for operations that can fail + +### Lambdas + +```cpp +// Good - explicit capture +connect(btn, &QPushButton::clicked, this, [this, id]() { + handleClick(id); +}); + +// Bad - default capture +connect(btn, &QPushButton::clicked, [=]() { ... }); +``` + +--- + +## Naming Conventions + +| Type | Format | Example | +|------|--------|---------| +| Class | PascalCase | `MainWindow` | +| Private member | `m_` + camelCase | `m_currentTheme` | +| Static member | `s_` + camelCase | `s_instance` | +| Public member | camelCase | `dateOfBirth` | +| Constant | SCREAMING_SNAKE | `MAX_VALUE` | +| Function | camelCase | `getCurrentTheme()` || Enum class | PascalCase | `enum class State` | +| Enum values | PascalCase | `State::Running` | + +**SCREAMING_SNAKE scope**: Use for `constexpr` constants, `#define` macros, and legacy `enum` values only. Prefer `enum class` with PascalCase values for new code. +--- + +## Headers + +### Include Guards + +```cpp +#pragma once +``` + +### Include Order + +1. Corresponding header +2. C++ standard library +3. Qt headers +4. Third-party headers +5. Project headers + +```cpp +#include "MyClass.h" + +#include <memory> +#include <string> + +#include <QObject> +#include <QString> + +#include "OtherClass.h" +``` + +**Note**: clang-format automatically reorders includes. Always accept its output. + +### Forward Declarations + +Prefer forward declarations over includes when possible: + +```cpp +// Good +class OtherClass; + +// Avoid +#include "OtherClass.h" +``` + +**Qt warning**: Forward declarations do not work for QObject-derived classes that use `Q_OBJECT`. These must be fully included. + +--- + +## Comments + +### Documentation + +```cpp +/// @brief Short description. +/// +/// Detailed description if needed. +/// @param input Description of parameter. +/// @return Description of return value. +bool doSomething(const QString& input); +``` + +### Implementation Comments + +```cpp +// Why this approach was chosen +// NOT what the code does +``` + +### TODOs + +```cpp +// TODO(username): Description of what needs to be done +// FIXME(username): Description of broken behavior that needs fixing +``` + +- **TODO**: Planned improvement or missing feature +- **FIXME**: Known bug or broken behavior requiring attention +- Username is required for traceability +- Compatible with IDE TODO/FIXME highlighting tools + +--- + +## Qt Widgets + +### UI Files + +- Use Qt Designer for layout +- Never edit generated `ui_*.h` files +- Set meaningful `objectName` values + +### Widget Classes + +- Keep UI logic minimal +- Delegate to core services +- Use signals/slots for communication + +--- + +## File Templates + +These templates apply only to new Project Tick–owned files. Do not modify license headers in upstream forked code. + +### Header (.h) + +```cpp +// SPDX-License-Identifier: GPL-3.0-only +// SPDX-FileCopyrightText: 2026 Project Tick + +#pragma once + +#include <QObject> + +class MyClass : public QObject { + Q_OBJECT + +public: + explicit MyClass(QObject* parent = nullptr); + ~MyClass() override; + +signals: + void somethingHappened(); + +private: + QString m_data; +}; +``` + +### Source (.cpp) + +```cpp +// SPDX-License-Identifier: GPL-3.0-only +// SPDX-FileCopyrightText: 2026 Project Tick + +#include "MyClass.h" + +MyClass::MyClass(QObject* parent) + : QObject(parent) +{ +} + +MyClass::~MyClass() = default; +``` + +--- + +## Related + +- [Project Structure](./PROJECT_STRUCTURE.md) +- [Architecture](./ARCHITECTURE.md) |