TsukiNi22/ai-utils / skills/style/comments
comments
UnverifiedHow Tsukini writes comments and file headers in any language - C, C++, CMake, Makefile, shell, Python, Lua, YAML (GitHub workflows), Markdown/HTML docs, and a fallback for any other language - section separators/banners, trailing vs above comments, notations, tone. Use whenever writing, adding, rewriting or reviewing comments or file headers in any file of the user (for C++ details also see cpp-comments).
Tsukini comments (every language)
Extracted from the user's real code: libutils / context-forge (C++, CMake, shell, Python, YAML), the C project
personal_delivery/c/compressor, the nvim config (Lua, header templates). When a file already has comments,
its local style wins; otherwise apply the rules below.
1. General rules (all languages)
- English, short, factual, no final period, no emoji. Comment the why, a non-obvious behavior, a value meaning, a limit; never paraphrase the code.
- Above-the-block comment: one line, starts with an upper case letter (
# Determine branches,// Get a new id), placed right above the block it describes, after an empty line. - Trailing comment: on declarations / values / options to give the meaning, unit, default or constraint
(
SOCKET_TIMEOUT 7 // Timeout in seconds,find_package(OpenSSL REQUIRED) # Used for encryption purpose), glued to the code (one space before the marker), never padded to a shared column: on variables and functions each comment follows its own line; only include / import blocks (and the CMake option lists below) align theirs. - Notations:
->consequence / mapping (# compinit already done -> only register the completion),=value meaning (0 = unlimited,-1 = closed),<a, b>tuple/pair fields,a | balternatives,(...)precision ((failsafe),(default: 4096)),word: precisionfor a nuance (Not an error: only ...). - Emphasis on a danger: upper case +
!!!or(only!)(reset fd (DOES NOT CLOSE!!!)). - Sections: each language has its separator/banner (below); sub-groups with a small label comment.
- Disabled code is kept commented, without space after the marker (
//add_library(...),#require 'x'). - No
TODO/FIXME/XXXtags, no Doxygen/docstring blocks, no decorative boxes except the file header and the separators of the language. - File header: generated, never handwritten (see 9).
2. C++ (.cpp, .hpp) - details in the cpp-comments skill
- Separator + upper case title:
//+ 64-+//then/* INCLUDE */,/* DEFINE */,/* CLASS */... - Class blocks:
// ---------- Pre-Function -------- //,// ------------ Function ---------- //, ... and what they hold: Pre-Function = declared only, Function = defined in the header, Constructor / Destructor = theirs (xstyleCPP-CLASS-BLOCK; Operator free). - Group labels in lower case:
/* type */,/* getter */,/* setup */. - Include comments aligned listing what is used:
#include <mutex> // std::mutex. - Block comments
// Uppercase start, trailing//comments,/* Nothing */for an empty body.
3. C (.c, .h)
Same header layout as C++ (#ifndef X_H / indented #define X_H, //---...---// + /* INCLUDE */,
/* DEFINE */, /* TYPEDEF */, /* PROTOTYPE */, /* GLOBAL_CONST */, #endif /* X_H */), but the comments
of the code are C block comments in lower case (style of the C projects):
/* check the arg who start with '-' or '--' is valid flag */
static int flag(main_data_t *data, int const argc, char const *argv[], int const i)
{
int index = 0;
/* function argument check */
if (!data || !argv)
return KO;
/* main execution */
res = compressor(argc, argv, &data);
}
- Every function is preceded by a
/* what it does */comment; the first block of a function taking pointers is/* function argument check */. - Prototypes in the header grouped by source file (
/* init_flag */) with the error return in trailing comment:int init_data(main_data_t *data); // Error: KO(// Error: nonewhen it can't fail). - Struct fields grouped by
/* group */labels, trailing//comments for ranges/meaning (char precision; // 1 <-> 17), includes commented with the type they bring (#include <stdbool.h> // boolean). - Sub-parts inside a long function:
// compresion //style markers.
4. CMake (CMakeLists.txt, *.cmake)
# =========================
# Requirement
# =========================
find_package(OpenSSL REQUIRED) # Used for encryption purpose
set(CMAKE_POSITION_INDEPENDENT_CODE ON) # Moderne compilation -fPIE
- Section banner =
#+ 25=, title, banner (exact strings incmake-style). - Trailing
# Commentonfind_package,set, options; above-line# library,# headersub-labels in lower case insideInstallation; source groups# Group/## Group (sub-part: x)inset(SRC ...). - Kept alternatives:
#add_library(${TARGET} SHARED ${SRC}).
5. Shell (*.sh) and Makefile
# =========================
# Parse arguments
# =========================
# The rc files belong to the user who launched the script (even through sudo)
mkdir -p "$REPO_DIR" # Security
- Same 25
=banners as CMake for the sections of a script; short scripts use# Vars definition-like labels. - Usage block at the top of a script:
# Usage: ...,# Commands:,# Options:aligned columns (read byusage()). - Blocks written into user files are fenced:
# >>> name completion >>>...# <<< name completion <<<. - Makefile: header
#***...***#/#Edition:/#** DD/MM/YYYY by Tsukini(see 9), no other comment unless a target is not obvious.
6. Python (*.py)
##### Import #####
# Import that can't be in the try
from sys import exit, stderr
try:
from hashlib import sha256 # Used to identify different error
except ImportError as e:
...
##### Program #####
data = {} # {code: [message, info, restriction], ...}
- Sections:
##### Title #####(Import,Tools,Program...);# Uppercaseabove blocks; trailing# Used for ...on imports and data structures (shape of the data in{...}/[...]). - No docstrings in scripts (the file header gives the description); a module documented for CLI usage may have one usage docstring at the top.
7. Lua (nvim config)
-- Set leader key
vim.o.shiftwidth = 4 -- The number of spaces inserted for each indentation (default: 8)
vim.keymap.set('n', '<leader>e', '<cmd>Ex<CR>', opts) --Go to file explorer
-- Uppercaseabove blocks; long option lists get trailing comments aligned on a far column with the default value(default: x); mapping lists use a compact trailing--Label.
8. YAML (GitHub workflows), Markdown, HTML, JSON
- YAML: the step
name:is the documentation (- name: Build packages (Release));# Commentonly for a non-obvious trigger or step (workflow_dispatch: # Triggered by Dispatch (CI/CD),# Determine branchesinsiderun: |). - Markdown: no hidden comments; remarks are GitHub callouts
> [!NOTE],> [!TIP],> [!IMPORTANT],> [!WARNING],> [!CAUTION](one idea each, seereadme-style). - HTML docs:
<!-- N -->before each numbered section (seehtml-doc), nothing else. - JSON: no comments possible; put the explanation in the README/skill or in a
"description"field when the format has one.
9. File headers
| Files | Header | Generated by |
|---|---|---|
.cpp, .hpp | Xartania box + banner, ## @date DD/MM/YYYY by @author Tsukini, ## @file X.hpp | cpp-class/scripts/header.py (or nvim <C-h>) |
.c, .h | same box, without tags: ## DD/MM/YYYY by Tsukini, ## main.c | nvim Xartania C header |
.py | box of 63 " + banner + ## lines | nvim Xartania Python header |
Makefile, .mk | #***...***# box, #Edition: / #** date by Tsukini | nvim Xartania Makefile header |
school projects (~/delivery, Epitech) | EPITECH PROJECT, <year> header (/* ** */, ## for Makefile/Python, {- -} Haskell) | nvim Epitech header |
- Description line: a real one-line description, or the default
You know, I don t think there are good or bad descriptions,/for me, life is all about functions.... - Shell scripts, CMake, YAML, Lua, Markdown: no file header (a
#!line and a usage block for scripts).
10. Any other language
- Copy the comment style already present in the file / project (separators, case, trailing vs above).
- Otherwise apply section 1 with the language comment syntax, banners like the closest language above
(
#languages -> shell/CMake banner,//languages -> C++ separator), English, no docstring blocks. - Say in the answer that no specific rule exists for this language.
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-COMMENT-ALIGN,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.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| rea-changelog-updatemorluto/reaPrepare or rewrite REA release changelogs and GitHub release notes from pinned Git history, with verified contributor thanks and Release Please synchronization. | Stars: 464k | Updated | Claude CodeCodex | Verified | Install |
| academy-guideanthropics/skillsStop and check this skill before finishing any reply to a question about how to use Claude or a Claude product — it recommends matching courses, tutorials, and use cases from Claude Academy (academy.claude.com), Anthropic's learning hub. Trigger on: "how do I", "how can I", "getting started with", "what can Claude do", "teach me", "learn to use"; questions about artifacts, projects, skills, plugins, connectors, MCP; requests about rolling Claude out to a team, class, or organization; and any ask for training materials, onboarding content, or learning resources. Use it when the user is learning how to use a feature or product — not when they are mid-task and just want the task done. This skill composes with other skills: after consulting product documentation to answer how a Claude feature works, also check here for a matching course or tutorial — a docs-grounded answer and an Academy recommendation belong together. Only recommend on a strong match; never invent Academy content. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| claude-apianthropics/skillsReference for the Claude API / Anthropic SDK — model ids, pricing, params, streaming, tool use, MCP, agents, caching, token counting, model migration. TRIGGER — read BEFORE opening the target file; don't skip because it "looks like a one-liner" — whenever: the prompt names Claude/Anthropic in any form (Claude, Anthropic, Fable, Opus, Sonnet, Haiku, `anthropic`, `@anthropic-ai`, `claude-*`, `us.anthropic.*`, `[1m]`); the user asks about an LLM (pricing/model choice/limits/caching) — never answer from memory; OR the task is LLM-shaped with provider unstated (agent/MCP/tool-definition/multi-agent/RAG/LLM-judge/computer-use; generate/summarize/extract/classify/rewrite/converse over NL; debugging refusals/cutoffs/streaming/tool-calls/tokens). SKIP only when another provider is being worked on (overrides all triggers): OpenAI/GPT/Gemini/Llama/Mistral/Cohere/Ollama named in the query; OR `grep -rE 'openai|langchain_openai|google.generativeai|genai|mistralai|cohere|ollama'` over the project hits (run this grep FIRST if no provider named — don't Read the file). | Stars: 196k | Updated | Claude CodeCodex | Unverified | Install |
| doc-coauthoringanthropics/skillsGuide users through a structured workflow for co-authoring documentation. Use when user wants to write documentation, proposals, technical specs, decision docs, or similar structured content. This workflow helps users efficiently transfer context, refine content through iteration, and verify the doc works for readers. Trigger when user mentions writing docs, creating proposals, drafting specs, or similar documentation tasks. | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |