TsukiNi22/ai-utils / skills/cpp/cpp-class
cpp-class
VerifiedGenerate C++ (C++20) .hpp/.cpp files and class architectures in Tsukini's style (Xartania header, indented include guards, INCLUDE/CLASS sections, Pre-Function/Function/Operator/Constructor/Destructor blocks, libutils attributes or standard [[...]]), with empty bodies only (never the logic), then register the .cpp in the CMakeLists.txt. Also creates the main.cpp entry point in the same style. Use whenever the user asks to create, scaffold or add a C++ class, a main / entry point, interface (I*), abstract class (A*), template, struct/Type or Define header, module or set of .hpp/.cpp files.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 10.5 KB |
| examples/ASocket.cpp | other | 11.7 KB |
| examples/ASocket.hpp | other | 7.5 KB |
| examples/ArgParserType.hpp | other | 3.6 KB |
| examples/ISocket.hpp | other | 5.4 KB |
| examples/IdHandler.hpp | other | 8.3 KB |
| examples/NetworkDefine.hpp | other | 1.1 KB |
| examples/Scheduler.cpp | other | 2.5 KB |
| examples/Scheduler.hpp | other | 4.7 KB |
| reference/layout.md | markdown | 17.5 KB |
| requires.txt | markdown | 32 B |
| scripts/cmake_add.pyexecutable | script | 4.7 KB |
| scripts/detect_libutils.shexecutable | script | 1.5 KB |
| scripts/fonts/ansi_shadow.flf | other | 11.9 KB |
| scripts/header.pyexecutable | script | 4.2 KB |
| scripts/list_attributes.shexecutable | script | 1.6 KB |
| templates/abstract.hpp | other | 1.5 KB |
| templates/class.cpp | other | 262 B |
| templates/class.hpp | other | 1.5 KB |
| templates/define.hpp | other | 463 B |
| templates/family.hpp | other | 417 B |
| templates/interface.hpp | other | 1.2 KB |
| templates/main-std.cpp | other | 474 B |
| templates/main.cpp | other | 753 B |
| templates/template.hpp | other | 1.6 KB |
| templates/type.hpp | other | 823 B |
reference/layout.md
View on GitHub# File & class layout (cpp-class)
Formatting, naming and spacing rules: the `cpp-style` skill (`../../cpp-style/SKILL.md`).
Comment rules: the `cpp-comments` skill (`../../cpp-comments/SKILL.md`).
The files in `../examples/` are the ground truth for the layout: when this document and an
example disagree, follow the example, but **never copy their function bodies** (see below).
## Empty bodies (mandatory, no exception)
This skill builds the **architecture only**. It never writes the content/logic of a function,
even when the user describes the behavior:
- `void` function / method / constructor -> body `/* Nothing */`.
- Non-void -> `/* Nothing */` then the smallest return that compiles:
`return {};`, `return *this;` (operators), `return false;`...
- The described behavior goes in a trailing comment on the declaration (`void cancel(std::size_t id); // cancel given task`), never in the body.
- A constructor / destructor / operator **defined in its class** (a header, a template) with an empty body is one
line: `Name(const int value): _value{value} { /* Nothing */ }; // what it does` (the `:` glued to the `)`), `~Name() noexcept { /* Nothing */ };`,
an operator `Name& operator=(Name&& other) noexcept {return *this;};` - never the `{` / `/* Nothing */` / `};`
block on several lines (`cpp-style`, xstyle `CPP-EMPTY-BODY`). The `.cpp` definitions keep the block form below.
- Only allowed, because it is not logic:
- `= default`, `= delete`, `= 0`;
- a constructor init list that only forwards the parameters to the members;
- accessors that only return or assign one member (`{return this->_fd;};`, `{this->_fd = fd;};`);
- a public wrapper that only forwards to its private `name_` implementation.
- the `main()` of `templates/main.cpp` (pure wiring: create the core class, `init`, `run`, catch, exit).
```cpp
_hot void utils::system::Scheduler::clear(void)
{
/* Nothing */
}
_cold std::size_t utils::system::Scheduler::count(void) const
{
/* Nothing */
return {};
}
```
## File header
Generated by `scripts/header.py` (never written by hand). Box of 64 chars, optional
ANSI Shadow banner (each line prefixed by one space), then:
```
Edition:
## @date DD/MM/YYYY by @author Tsukini
File Name:
## @file Name.hpp
File Description:
## <one line description>
```
Default description (when there is nothing meaningful to say, typically in a .cpp):
`You know, I don t think there are good or bad descriptions,` / `for me, life is all about functions...`
## .hpp layout
```
<header>
#ifndef NAME_H
#define NAME_H
//----------------------------------------------------------------//
/* INCLUDE */
/* type */
#include "../attribute/Attribute.hpp" // _cold, _hot
#include <vector> // std::vector
//----------------------------------------------------------------//
/* DEFINE */ (only if needed, indented like the includes)
namespace a::b { // namespace start
//----------------------------------------------------------------//
/* PROTOTYPE */ (only if needed: free functions, forward declarations of classes)
//----------------------------------------------------------------//
/* TYPEDEF */ /* ENUM */ /* STRUCT */ /* CLASS */
} // namespace end
//----------------------------------------------------------------//
/* MIGRATION */ (only for deprecated aliases, _migration(x, y, z))
#endif /* NAME_H */
```
- Guard = file name in upper case without separator + `_H` (`IdHandler.hpp` -> `IDHANDLER_H`,
`ArgParserType.hpp` -> `ARGPARSERTYPE_H`). `#define` is indented by 4 spaces.
- Includes inside a header, in the order of `cpp-style` "Includes": the libutils `#define _Section` lines, the
personal libraries (`<utils/utils.hpp>`), the project files with a **relative** path (`"../../EngineType.hpp"`,
`"ISocket.hpp"`), then the external / standard libraries; a `#define` an include needs on the line just before
it; in each group the longest name first, the most complex first at equal length; each include has a trailing
comment, **aligned** on the same column, listing what is used (`// std::mutex, std::unique_lock`).
- Namespace: see the "Namespaces" section below.
- Free functions in `/* PROTOTYPE */`, grouped under small `/* group */` comments.
- **Each kind of declaration in its own section**, never mixed:
- `/* TYPEDEF */`: every `using X = ...;` / `typedef ... X;` alias (an alias template too), each one with its
trailing comment when the name isn't enough;
- `/* ENUM */`: the `enum class`;
- `/* STRUCT */`: every `struct` / `union` (data types, template specializations like `std::hash<X>`, forward
declarations `struct sockaddr;` included);
- `/* CLASS */`: the classes.
Default order `TYPEDEF`, `ENUM`, `STRUCT`, `CLASS`. An alias that names a struct / enum of the same file needs it
first: its `/* TYPEDEF */` section goes right **after** the section that defines that type (a section can be
written twice when the order requires it: `TYPEDEF` of the plain aliases, `STRUCT`, `TYPEDEF` of the aliases of
these structs). Types declared outside a namespace (ex: POSIX types provided on Windows) follow the same
sections, at column 0 before the `namespace` line.
- **Preprocessor conditionals in the sections** (rule of `cpp-style`, "Indentation & braces"): the directive at the
indentation of the section content, the content one level more, and one conditional **per section** (never one
`#ifdef` spanning several sections):
```cpp
//----------------------------------------------------------------//
/* DEFINE */
#ifdef UTILS_WINDOWS
#define EPOLLIN 0x001u
#endif
//----------------------------------------------------------------//
/* STRUCT */
#ifdef UTILS_WINDOWS
union epoll_data {
void* ptr;
int fd;
};
#endif
//----------------------------------------------------------------//
/* TYPEDEF */
#ifdef UTILS_WINDOWS
typedef union epoll_data epoll_data_t;
#endif
```
## Namespaces (how to set them up)
Rules observed on the ~90 headers of libutils:
1. **Root namespace = project/library name** (`utils`), every file of the project is inside it.
A new project without convention: root = project name in lower case (`rtype`, `sos`).
2. **One level per section folder** under `include/<root>/`: `include/utils/system/` -> `utils::system`,
`include/utils/security/encryption/` -> `utils::security::encryption`.
3. **Grouping-only folders don't create a level.** A folder that only sorts files gives its
children's namespace directly:
- `manip/iomanip/` -> `utils::iomanip`, `manip/smanip/` -> `utils::smanip` (no `utils::manip`);
- `exception/basic/`, `exception/custom/` -> `utils::exception`.
4. **A family folder (one concept: `IX`, `AX`, implementations) stays in the parent namespace**:
`network/socket/{ISocket,ASocket,TCPSocket}.hpp` -> `utils::network`,
`pool/middleware/*.hpp` -> `utils::pool`.
5. **A sub-part with its own identity gets its own level**: `smanip/codec/` -> `utils::smanip::codec`,
`smanip/parser/` -> `utils::smanip::parser`, `math/geometry/` -> `utils::math::geometry`.
6. **Internals in a nested namespace** next to the public one: `utils::encapsulation::shm`
(SharedMemory metadata), `utils::security::observer::instances`, `utils::algorithms::sos::tools`.
7. Names: lower case, short, one word, abbreviated when long (`c2dmp-hsm` -> `c2dmp`, `shm`).
8. **Family / umbrella header** without namespace: `Socket.hpp`, `Parser.hpp`, `Codec.hpp`
only include the files of the family, grouped by `/* interface */`, `/* tools */`, `/* <kind> */`
(template `templates/family.hpp`); the root `include/<root>/<root>.hpp` includes every section.
9. Always nested syntax on one line: `namespace utils::network { // namespace start`, never
`namespace utils { namespace network {`. One namespace block per file (+ the `MIGRATION` one).
10. **Moving a type to another namespace**: keep the old name with a migration alias at the end of the file:
```cpp
//----------------------------------------------------------------//
/* MIGRATION */
namespace utils::network {
using ISocket _migration(4, 0, 0) = utils::network::ISocket;
_migration(4, 0, 0) inline bool is_ip(const std::string& s) {return utils::network::is_ip(s);};
}
```
11. Inside the code, every project symbol is fully qualified from the root (`utils::network::Address`),
even from the same namespace; no `using namespace`.
Before creating files, decide the namespace of each one with these rules, show the tree
(`include/<path>/X.hpp -> ns`) in the AskUserQuestion call when a choice is ambiguous
(grouping vs section folder, new sub-part vs family).
## Class layout
Visibility order: `private` (or `protected`) **first**, then `public`.
Inside each visibility, in this order (a block with nothing linked to it is removed, see below):
```
// ---------- Pre-Function -------- // declarations only (defined in the .cpp)
// ------------ Function ---------- // defined inline in the header (templates, one-liners)
// ------------ Operator ---------- //
// ---------- Constructor --------- //
// ----------- Destructor --------- //
```
- **Each declaration in its block** (checked by `xstyle`, rule `CPP-CLASS-BLOCK`, in a class that uses the
blocks; a class without them, a plain struct, is free):
- `Pre-Function`: functions **declared only** (`T f(...);`, a pure `virtual ... = 0;`), their body in the
`.cpp`; never a body here, never a constructor / destructor / data member.
- `Function`: functions **defined in the header** (`{...};` one-liners and templates, `= default` /
`= delete` of a plain function); a bare declaration goes to `Pre-Function` instead.
- `Constructor` / `Destructor`: only `X(...)` / `~X()` (their `= default` / `= delete` included), never mixed
(a destructor gets its own `Destructor` block, even when it is the only line).
- Data members: first, before the blocks of their visibility, never under a block.
- `Operator`: free. `operator=`, `operator==`, a conversion `operator T()`... go there by default, but an
operator elsewhere or something else in it is only a hint of review, never an error (`xstyle` ignores it).
- **No empty section**: a separator (class block `// --- X --- //` or file section `/* DEFINE */`,
`/* PROTOTYPE */`, `/* ENUM */`...) is only written when at least one declaration is linked to it.
No Pre-Function in `private` -> no `// ---------- Pre-Function -------- //` there; same for
Function, Operator, Constructor, Destructor (all of them, no exception), a visibility left empty
is removed too, and an empty `/* group */` label as well. Never leave a separator followed by
nothing or directly by the next separator.
- **Short functions are inlined in the header**: getters, setters, one-member accessors, wrappers
forwarding to their `name_` implementation and any function whose body is a single statement (what
would be the 2-line .cpp form `signature` + `{return ...;}`, a small computation included) are defined in the
`// ------------ Function ---------- //` block of the `.hpp` with the `inline` keyword after the
attributes (`_cold _nodiscard inline T id(void) const {return this->_id;};`, see `Scheduler.hpp`,
`IdHandler.hpp`), never declared in Pre-Function and defined in the .cpp: the compiler can then
inline them at the call site. Only when it can help: a `virtual` method (`override`/`final`) is
still defined in the header when short but without `inline` (pointless on a virtual call), and a
function with real logic (more than one statement), or whose body needs an include the header doesn't
have otherwise, stays in the .cpp.
- Members first (before the blocks), with their default value at the declaration,
grouped under `/* group */` comments when there are many.
- Sub-groups inside a block: `/* setup */`, `/* setter */`, `/* getter */`, `/* raw */`, `/* parsing */`...
- Every private, protected or internal function (not part of the public API) is named `<name>(<Name>)*_`:
camelCase with a trailing `_` (`allocate_`, `computeHash_`, `readChunkHeader_`), the implementation
behind a public wrapper included (`cancel()` -> `cancel_()`). Public methods keep plain camelCase, free
tool functions keep snake_case. Constructors, destructors, operators and the `override`/`final` of a
public interface method keep their name.
- Default rule of five (unless the class needs otherwise):
```
// ------------ Operator ---------- //
X& operator=(const X& other) = delete;
X& operator=(X&& other) = delete;
// ---------- Constructor --------- //
X() = default;
X(const X& other) = delete;
X(X&& other) = delete;
// ----------- Destructor --------- //
~X() = default;
```
- `static_assert` right after the class opening for template constraints.
- Thread safe class: `mutable std::mutex _lock; // Handling of multithreading` and a
`const bool safe_mode = true` parameter on the methods (see `IdHandler.hpp`).
## Hierarchy / file kinds
- `IName`: interface, every method `virtual ... = 0`, `virtual ~IName() = default;`, `protected` then `public`.
- `AName`: abstract base, `public IName`, implemented methods marked `final` (or `override` when a
child may redefine), `protected` members.
- `Name`: concrete class.
- `NameType.hpp`: `/* STRUCT */` + `/* TYPEDEF */` (the `using` aliases). `NameDefine.hpp`: `/* DEFINE */` macros
+ `/* ENUM */` `enum class`.
- Template class: everything in the .hpp (no .cpp), bodies still empty.
## .cpp layout
```
<header>
#define _Attribute
#include <utils/utils.hpp>
#include "module/Name.hpp"
#include <string>
ns::Name::Name(const std::string& name)
: _name{name}
{
/* Nothing */
}
_hot void ns::Name::method(void)
{
/* Nothing */
}
```
- Includes in the order of `cpp-style` "Includes": the `#define _Section` lines + `<utils/utils.hpp>` (libutils
projects, sections of what the .cpp itself uses), the project ones with the path **from `include/`**, then the
external / standard ones; longest name first in each group; no comments.
- No `namespace x {}` block: every definition is fully qualified.
- Same order as the declarations in the header.
## Attributes
`scripts/detect_libutils.sh <project>` decides:
- `internal` (inside libutils): macros + `#include "../attribute/Attribute.hpp"` (relative) in headers,
`"utils/attribute/Attribute.hpp"` in .cpp.
- `libutils`: macros + `#include <utils/utils.hpp>` (comment aligned like the others), see below.
- `std`: standard attributes (mapping table in `cpp-style`), no Attribute include.
## libutils includes (every project using libutils, not libutils itself)
Every libutils header is reached through the root include, never one by one:
`#include <utils/utils.hpp>` (preferred; `<utils.hpp>`, `"utils/utils.hpp"` or `"utils.hpp"` also accepted
when the project already uses that form). Never `"utils/attribute/Attribute.hpp"`,
`<utils/network/Server.hpp>`... directly, in a .hpp as in a .cpp. Only exception: a header that
`utils.hpp` does not give, like the observers (`<utils/security/observer/Observer.hpp>`...), is
included directly. The trailing comment of the root include lists what is used
(`#include <utils/utils.hpp> // _cold, _nodiscard, utils::system::Scheduler`), aligned with the others.
Inside libutils itself (`internal` mode) the includes stay relative (`"../attribute/Attribute.hpp"`) and are
project includes (sorted with the other project headers).
**Sections (mandatory)**: every file (.hpp and .cpp) defines the sections it uses at the top of its includes,
right before the root include (the personal libraries come first, `cpp-style` "Includes"), one `#define` per line
(indented like the includes in a header):
```cpp
#define _Attribute
#define _System
#include <utils/utils.hpp> // _cold, _nodiscard, utils::system::IdHandler
#include "../EngineType.hpp" // rtype::engine::Id
#include <memory> // std::unique_ptr
```
Why: `utils.hpp` has no global include guard, it only includes the sections defined before it (everything
when none is) and these `#define` stay set for the rest of the translation unit. A file that includes it
bare after another one defined `_Exception` only gets the exceptions (ex: `main.cpp` with `_Exception` +
`_Attribute`, then a header needing `utils::network::Server` -> not declared). Redefining the same section
in several files is harmless.
| Used | Section |
|---|---|
| attribute macros (`_hot`, `_nodiscard`, `_alignas`, `_ctor`...) | `_Attribute` |
| `utils::exception::*`, `OK`/`KO` | `_Exception` |
| `onBasicVerbose`, `set_verbose`... | `_Verbose` |
| `utils::arguments::ArgParser`, `Settings` | `_Arguments` |
| `utils::cli::*` | `_Cli` |
| `utils::network::Server` / `Client` / `Address` / `Payload` | `_Network` (also gives `_Socket`) |
| `utils::network::ISocket` / `ASocket` / `TCPSocket` alone (were in `utils::network::socket` before v3.0.0) | `_Socket` |
| `utils::system::IdHandler` / `Scheduler` / `LoadBalancer` | `_System` |
| `utils::math::*` (`Coord2D`, `rotate_point_*`...) | `_Math` |
| `utils::iomanip::*` (`Char`, `Color`, ANSI) | `_IOManip` |
| `utils::smanip::*` (`format`, codecs, `IParser` / `AParser`) | `_SManip` |
| `utils::type::*` | `_CustomType` (`_Vector`, `_BLT`) |
| `utils::encapsulation::*` | `_Encapsulation` |
| `utils::pool::*` | `_Pool` |
| `utils::security::encryption::*` | `_Encryption` |
| concepts / algorithms | `_Concepts` / `_C2DMP`, `_SOS` |
Groups: `_Handling` (exception, verbose, pool, cli, arguments, network), `_Tools` (math, concepts,
encapsulation, system, custom types, manip, algorithms, security). Exact list: `utils/utils.hpp` of the
installed version.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 193k | Updated | Claude CodeCodex | Verified | Install |