TsukiNi22/ai-utils / skills/cpp/cpp-comments
cpp-comments
VerifiedHow Tsukini writes comments in C++ (from libutils) - section separators, /* group */ labels, trailing comments on declarations and includes, short English block comments, no Doxygen. Use whenever adding, rewriting or reviewing comments in C/C++ code for the user, or when generating C++ code that needs comments.
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.9 KB |
| requires.txt | markdown | 10 B |
SKILL.md
View on GitHub---
name: cpp-comments
description: How Tsukini writes comments in C++ (from libutils) - section separators, /* group */ labels, trailing comments on declarations and includes, short English block comments, no Doxygen. Use whenever adding, rewriting or reviewing comments in C/C++ code for the user, or when generating C++ code that needs comments.
metadata:
summary: 'How I comment C++ code: section separators, `/* group */` labels, aligned trailing comments, no Doxygen.'
---
# Tsukini comment style (C++)
Always in **English**, short, no final period, never Doxygen (`@brief`/`@param`/`///` are never used,
the only `@` tags are `@date`/`@author`/`@file` of the file header).
Comment the **why** and the non-obvious behavior, never paraphrase the code.
## 1. Structure comments (exact strings)
Section separator (64 `-`), then the section title in upper case:
```cpp
//----------------------------------------------------------------//
/* INCLUDE */
```
Titles: `INCLUDE`, `DEFINE`, `MACRO`, `TYPEDEF`, `ENUM`, `STRUCT`, `PROTOTYPE`, `CLASS`, `MIGRATION` (`TYPE` is
the old name of `TYPEDEF`: rename it when editing a file). `TYPEDEF` holds the `using` / `typedef` aliases, `STRUCT`
the `struct` / `union` (forward declarations included), never mixed (`cpp-class` `reference/layout.md`).
Indented by 4 inside the include guard (INCLUDE/DEFINE), at column 0 after `namespace x {` (and for the types
declared at column 0 before it).
Class blocks (exact strings, aligned like this):
```cpp
// ---------- Pre-Function -------- //
// ------------ Function ---------- //
// ------------ Operator ---------- //
// ---------- Constructor --------- //
// ----------- Destructor --------- //
```
A section separator or class block is only written when something is linked to it: never leave one empty.
The blocks say what they hold (`xstyle` rule `CPP-CLASS-BLOCK`): `Pre-Function` = declarations only (body in the
.cpp), `Function` = defined in the header, `Constructor` / `Destructor` = theirs, data members above the blocks;
`Operator` is free (a hint, never an error). Details: `reference/layout.md` of `cpp-class`.
Group labels, lower case, `/* ... */`, on their own line above the group:
`/* type */`, `/* setup */`, `/* setter */`, `/* getter */`, `/* raw */`, `/* parsing */`, `/* tools */`,
`/* limits */`, `/* sub parsing */`, `/* hook handling */`, `/* destruction */`...
Sub-group in the code of the `.cpp` with a plain line comment: `// Long`, `// Short & Flag`.
Namespace delimiters: `namespace utils::system { // namespace start` ... `} // namespace end`.
Guard end: `#endif /* NAME_H */`.
## 2. Trailing comments (the most used)
On declarations, to give the meaning, the default, the unit or the constraint:
```cpp
int _fd = -1; // -1 = closed, can exec connect or listen
bool _mode = false; // true: server | false: client
#define SOCKET_TIMEOUT 7 // Timeout in seconds
void cancel(std::size_t id); // cancel given task
virtual void reset(void) = 0; // reset fd (DOES NOT CLOSE!!!)
std::vector<std::tuple<std::string, bool, std::vector<std::string>>> arguments; // <id, option(true)|flag(false), {option}>
template<bool force = false> // Can't override an exiting one by default, throw of error
```
- **Glued to the code**: one space before `//`, on members, functions and one-liners alike; **never a column of
comments** (the only aligned trailing comments are the includes, below):
```cpp
std::vector<brain::BrainNeuron> _neurons; // every neuron of the 2d space
std::pair<brain::FType, brain::FType> _size = {1.0, 1.0}; // <width, height> of the 2d space
brain::UIType _neuron = 0; // number of neurons
_cold inline void seed(const brain::IType seed) {this->_seed = seed;}; // seed of the random generator (0 = random)
```
not `_neurons; // every neuron` padded to the longest line.
- Tuples / pairs described with `<field, field>`, alternatives with `|`, mappings with `->`,
values with `=` (`0 = unlimited`, `-1 = every fd`), precisions in `(...)`.
- Emphasis on a dangerous behavior in upper case + `!!!` or `(only!)`.
- Includes: every include of a header has an **aligned** trailing comment listing what is used:
```cpp
#include "../attribute/Attribute.hpp" // _hot, _cold, _unlikely, _likely, _nodiscard
#include <mutex> // std::mutex
```
Use `utils::exception::* (Type)` when many symbols come from the same header.
`.cpp` includes have no comment.
- In code, at the end of a line for a precision: `if (...) return; // called by the task itself: nothing to cancel`.
## 3. Line comments above a block
```cpp
// Get a new id
std::size_t id = this->_idHandler.allocate();
// Setup the new thread
...
// Only if the id wasn't already free
if (!this->_freeIds.insert(id).second) _unlikely {
```
- Start with an upper case letter, no final period, one line, describe the intent of the block.
- `word: precision` form for a nuance: `// Not an error: only this usage is invalid, the other usages can still accept the flag`.
- Tiny labels in lower case are fine: `// child`, `// parent`, `// left`.
## 4. Multi-line comments (rare)
For a note, a legend or a kept formula:
```cpp
/*
* DEFAULT -> Basic term
* TERM1 -> Advanced term
*/
/* --- Different Messages ---
* legacy -> Only kept for backward compatibility; no removal in sight ._.
* migration -> Retained for backward compatibility; will be removed in a future version
*/
```
`/*` alone (or with a `--- Title ---`), lines starting with ` * `, closing `*/` aligned on the `/*`.
## 5. Misc
- Empty body: `/* Nothing */` (an empty constructor / destructor / operator defined in its class: on its line,
`{ /* Nothing */ };` then its trailing comment; an init list there: `Name(int a): _a{a} { /* Nothing */ };`).
- Disabled code kept with `//` and no space (`//add_library(${TARGET} SHARED ${SRC})`).
- No `TODO`/`FIXME` tags in the code: describe the limitation in a normal comment instead.
- No decorative boxes or banners except the file header and the separators above.
## Checking (xstyle)
When `xstyle` is installed (`command -v xstyle`), check what was written or reviewed with it instead of re-reading the
rules by hand: `xstyle --rtk <files|dirs> [-r]` (**always `--rtk`**: compact output made for the assistant),
`xstyle --rtk --fix [CODES] <paths>` for the fixable ones (`-n` to preview), `-c CPP-DOXYGEN,CPP-INCLUDE-COMMENT,CPP-COMMENT-ALIGN,CPP-EMPTY-SECTION,CPP-ORPHAN-GROUP,CPP-NAMESPACE-COMMENT,G-TODO` for the rules of this
skill, `xstyle -x CODE` to explain one. Not installed: apply the rules by hand and say once that
`curl -fsSL https://tsukini22.github.io/my-universe/install.sh | bash -s` then `sudo dnf|apt|pacman install xstyle` (packages of [my-universe](https://tsukini22.github.io/my-universe/), sources: [TsukiNi22/xstyle](https://github.com/TsukiNi22/xstyle); no curl: `wget -qO-` instead of `curl -fsSL`) would check them. Its findings are heuristic: the local style of a file wins.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| receiving-code-reviewobra/superpowersUse when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| using-git-worktreesobra/superpowersUse when starting feature work that needs isolation from current workspace or before executing implementation plans - ensures an isolated workspace exists via native tools or git worktree fallback | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |
| verification-before-completionobra/superpowersUse when about to claim work is complete, fixed, or passing, before committing or creating PRs - requires running verification commands and confirming output before making any success claims; evidence before assertions always | Stars: 322k | Updated | Claude CodeCodex | Verified | Install |