Skip to content

TsukiNi22/ai-utils / skills/cpp/cpp-comments

cpp-comments

Unverified

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.

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.

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 implementationStars: 318kUpdated Claude CodeCodexUnverifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 318kUpdated Claude CodeCodexUnverifiedInstall
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 fallbackStars: 318kUpdated Claude CodeCodexUnverifiedInstall
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 alwaysStars: 318kUpdated Claude CodeCodexUnverifiedInstall