cpp-comments
Skill1 starsChanged 3 days agoMITView on GitHub
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.
- Pipes a download into a shell
In this repository70 other files it gives its agents.
- CLAUDE.mdCLAUDE.md
- ask-at-endSkill
- clarifySkill
- continue-workSkill
- exportSkill
- full-permissionSkill
- ideationSkill
- interactive-questionsSkill
- onboardSkill
- pauseSkill
- presentationSkill
- rtkSkill
- setup-contextSkill
- write-like-meSkill
- audit-bugsSkill
- audit-depsSkill
- audit-qualitySkill
- audit-securitySkill
- benchmarkSkill
- cmake-styleSkill
- cpp-classSkill
- cpp-projectSkill
- cpp-styleSkill
- better-explain-docSkill
- better-html-docSkill
- better-html-styleSkill
- better-protocol-docSkill
- docs-updateSkill
- explain-docSkill
- html-docSkill
- html-styleSkill
- protocol-docSkill
- readme-styleSkill
- reportSkill
- wiki-styleSkill
- ci-cdSkill
- git-commitSkill
- git-conventionsSkill
- pre-commitSkill
- legal-checkSkill
- legal-setupSkill
- licenseSkill
- libutils-exceptionSkill
- libutils-installSkill
- libutils-setupSkill
- libutilsSkill
- python-classSkill
- python-commentsSkill
- python-projectSkill
- python-styleSkill
- auditSkill
- cppSkill
- devSkill
- docSkill
- gitSkill
- legalSkill
- pythonSkill
- setup-projectSkill
- styleSkill
- setup-studioSkill
- The first 60 shown.
The file
We split this skill into the rules it gives an agent
5 rules. About 0 are common, 2 are distinctive, and 3 are very specific to this project.
≈0
Common · estimate
Many files like this have a rule of this kind.
≈2
Distinctive · estimate
This author's own choices. Worth a look.
3
Very specific
Tied to their project's names, files or tools. Probably skip.
- Common
- Distinctive
- Very specific
- Very specific: line 10
Always in English, short, no final period, never Doxygen (@brief/@param//// are never used, the only @ tags are @date/@author/@file of the …
- Very specific: line 75
Use utils::exception::* (Type) when many symbols come from the same header.
- Distinctive: line 90
Start with an upper case letter, no final period, one line, describe the intent of the block.
- Distinctive: line 113
No decorative boxes or banners except the file header and the separators above.
- Very specific: line 116
When xstyle is installed (command -v xstyle), check what was written or reviewed with it instead of re-reading the rules by hand: xstyle …
≈ “Common” is an estimate: at least 1 in 5 of the 364,980 skill files we read have a rule of the same kind, not the same words. “Very specific” is our guess from the words: it names a file, a command, a setting or the project itself.
Files
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:
//----------------------------------------------------------------//
/* 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):
// ---------- 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:
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):
notstd::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)_neurons; // every neuronpadded 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:
Use#include "../attribute/Attribute.hpp" // _hot, _cold, _unlikely, _likely, _nodiscard #include <mutex> // std::mutexutils::exception::* (Type)when many symbols come from the same header..cppincludes 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
// 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: precisionform 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:
/*
* 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/FIXMEtags 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, sources: TsukiNi22/xstyle; no curl: wget -qO- instead of curl -fsSL) would check them. Its findings are heuristic: the local style of a file wins.
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

