AGENTS.md

1# AGENTS.md
2 
3## Review guidelines
4 
5- Prioritize correctness, lack of regressions, performance, API stability, and code clarity and readability.
6- For performance-sensitive paths, flag obvious algorithmic regressions or slow paths.
7- For tests, flag missing coverage for changed or new behavior, as long as the testing framework is capable of testing it.
8- For config changes (new / removed options) remind the author to make a separate wiki PR if they haven't linked one yet.
9- Flag silent config breakage: e.g. changing an existing option's behavior. This is not allowed.
10- Flag bad config style that breaks this project's style guidelines (further below) and suggest fixes.
11- Flag bad code approaches that break this project's core code guidelines (further below) and suggest improvements.
12 
13## Style guidelines
14 
15- Code must be clang-formatted according to `.clang-format`.
16- single-line if and else statements must come without braces. This rule applies only to if / else, not do / while / other.
17- Avoid function bodies in headers as much as possible.
18- Avoid namespace {} in source files to mark local functions. Prefer `static`.
19- Prefer guards in functions and loops: `if (!cond) continue;`
20- Prefer forward-declaration in headers to inclusion.
21- Leave a stray `,` at the end of brace-enclosed lists to make formatting easier to read.
22- Leave a `;` inside empty function bodies for formatting.
23- Naming conventions:
24 - class: `CMyClass`
25 - struct: `SMyStruct`
26 - interface: `IMyInterface`
27 - class (not struct) member variables: `m_variable`
28- Do not use absolute includes from `src/` in headers: instead of `#include "a/b.hpp"` use `#include "../a/b.hpp"` for example. Protocol headers do not require this.
29 
30## Core code guidelines
31 
32- Stick to good code practices:
33 - Avoid complex classes / functions, prefer SRP.
34 - Consider using an observer pattern via hyprutils Signals where appropriate.
35 - Consider classic OOP patterns where appropriate: Strategy, Singleton, Proxy, etc.
36 - Watch out for typical bad practices in code: feature envy, LSP, etc.
37 - Use templating and inheritance to clean up code where appropriate.
38 - For obtaining singletons, use a `UP<CClass>& myClass();` pattern inside a namespace. This can be implemented in source as making and returning a static ptr.
39- Do not, under any circumstance:
40 - `using namespace std;`
41 - leave uninitialized primitives (int, float, etc)
42- Avoid, unless absolutely necessary:
43 - the C standard library. Use the C++ STL.
44 - `malloc` / `free` / etc
45 - C-style pointers. Use SP<> WP<> and UP<> from hyprutils. These are Shared, Weak and Unique pointers respectively. C-style pointers may be used in select scenarios (e.g. destroying fns, where it's impossible to make a mistake) but everywhere else must not be used unless necessary.
46 - C-style casts. Use rc<>, sc<>, or cc<> from hyprutils. These are shorthands to equivalent C++ casts.
47- Avoid:
48 - violating clang-tidy (`.clang-tidy`)
49 - manual C-style cleanup: `some_c_thing_new()` and `some_c_thing_free()` can be wrapped.
50- Make sure to write tests for code which our Unit (`tests/`) or Integration (`hyprtester/`) tests can test.
51