agentleFS
TsukiNi22TsukiNi22/ai-utils/skills/cpp/cpp-comments/SKILL.md

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

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
  1. Very specific:

    Always in English, short, no final period, never Doxygen (@brief/@param//// are never used, the only @ tags are @date/@author/@file of the …

    line 10
  2. Very specific:

    Use utils::exception::* (Type) when many symbols come from the same header.

    line 75
  3. Distinctive:

    Start with an upper case letter, no final period, one line, describe the intent of the block.

    line 90
  4. Distinctive:

    No decorative boxes or banners except the file header and the separators above.

    line 113
  5. Very specific:

    When xstyle is installed (command -v xstyle), check what was written or reviewed with it instead of re-reading the rules by hand: xstyle …

    line 116

≈ “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.

Keep what fits and drop the rest. Your version, ready for your agents.
Files
SKILL.md

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):
    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:
    #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

    // 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:

/*
 * 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, 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.

Download now (ZIP)

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
What did you use it for? e.g. Reviewing pull requests in a Rails app

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.