TsukiNi22/ai-utils / skills/style/coding-style
coding-style
UnverifiedTsukini coding style (any language except C++)
The C++ rules (cpp-style) are the reference: the same spirit applies everywhere. When editing an existing file, its
local style wins. Comments: the comments skill. Everything (code, identifiers, comments, messages) in English.
Common rules
-
4 spaces, never tabs (except where the language requires them: Makefile recipes, Go
gofmt). No trailing whitespace, one empty line between blocks, never two. -
Explicit over implicit: write the types when the language allows it (TS types, Python type hints for parameters/returns, Rust/Go explicit types on public items); no
any/ untypedvar/ inferred public APIs unless the user asks (same rule as noautoin C++, iterators and destructuring excepted). -
Naming: types
PascalCase, functions/methodscamelCase(Python, shell, Rust, C:snake_caseas the language wants), constantsUPPER_SNAKE, private members_namewhere the language has noprivate, special mode flagssnake_casewith a default value. -
Layout in sections with the banner of the language (see below): imports / constants / tools / program.
-
Errors: never silent. Message on stderr naming the file/context, explicit exit code (
0ok,1error,255special/fatal), early returns, failsafe options rather than crashes. -
Short functions, early returns, no magic number (named constant with a trailing comment), no dead code (kept commented only when it is a real alternative).
-
Alignment: columns only within a group of consecutive lines of the same category (the setters, the getters, the cases of one switch), tight (the longest line of the group + one space, counted, never guessed: not a space more on the longest line, no line padded past the column), every line of the group on that column. Lengths far apart (a jump of more than ~12 columns): align by levels - the short lines together on their tight column, the long ones on theirs, short level first, no blank line between (categories mixed if needed); a level needs two lines or more, a lone line joins the closest level and takes its column (see
cpp-style, checked in C++ by xstyleCPP-ONELINER-ALIGN). Trailing comments are glued to the code, one space before the marker (timeout = 7 # seconds,int fd = -1; // closed), never on a shared column; the exceptions are the include / import comments (one column per block) and formats whose own convention aligns (CMake option lists, the trailing;comments of consecutive assembly lines). -
Imports / includes explicit (no wildcard import), always in this order (same rule as the C++ includes of
cpp-style):- what the personal libraries need before being imported (a C
#define, an environment variable, a path added tosys.path...); - the personal libraries (the user's own libraries / packages);
- the project modules, each with what it needs (define, setting) on the line just before it;
- the external and standard libraries, each with what it needs on the line just before it.
Inside each group: the longest module name first, down to the shortest; between names of the same length, the most complex / specialized module first. When the project enforces another order with a tool (
gofmt/goimports,rustfmt,isort/ruff, eslintimport/order), the tool's order wins. - what the personal libraries need before being imported (a C
Python (from libutils cmake/scripts/*.py)
""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""" # Xartania header (comments skill)
...
"""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""""
##### Import #####
# Import that can't be in the try
from sys import exit, stderr
# Import that can be checked
try:
from pathlib import Path # Used to create & edit files
import json # Used to get the json data
except ImportError as e:
stderr.write(f"Import Error ({__file__}): {e}\n")
exit(255)
# Check if the program is call and not imported
if __name__ != "__main__":
stderr.write(f"The {__file__} can only be executed and not imported!\n")
exit(255)
##### Tools #####
def uint64_hash(s: str) -> int:
...
##### Program #####
from module import nameexplicit, each import with a trailing# Used for ...; optional dependencies in atrywith an explicit error.- Constants in
@dataclass(frozen=True)classes (Return.OK,Error.FATAL), shared in aconst.py. snake_casefunctions/variables, f-strings,with open(..., encoding="utf-8"),stderr.write+exit(code)for errors (no bareprintfor errors), guard__main__(script) or the opposite (module only imported).- Type hints on new functions (
-> int), no docstrings in scripts (a trailing comment is enough); a class keeps a short indented docstring likeconst.py.
Shell / bash (from libutils / context-forge setup.sh, check_files.sh)
#!/bin/bash
set -euo pipefail
BASE_URL="https://..."
SUDO="sudo"
# =========================
# Parse arguments
# =========================
usage() {
echo "Usage: $0 [--no-sudo]"
exit 1
}
for arg in "$@"; do
case "$arg" in
--no-sudo) SUDO="" ;;
-h|--help) usage ;;
*) echo "Error: unknown argument '$arg'" >&2; usage ;;
esac
done
set -euo pipefail,#!/bin/bash(bash features used), configuration variablesUPPER_SNAKEat the top, functionssnake_case(install_rpm_repo,is_rpm_based), sections with the 3-line# =====banner.- Always quote expansions (
"$var","$@"),[[ ]]for tests,command -vto check tools (require curl), errors on stderr (>&2) withError: ...,usage()printing the help and exiting. - Long options
--name, a-h|--help,$SUDOvariable to allow--no-sudo; idempotent scripts (re-running changes nothing), markers# >>> name >>>/# <<< name <<<for blocks written in user files.
Lua (from ~/.config/nvim)
- 4 spaces,
localeverything,snake_case/camelCaselike the surrounding file,require 'module'for configs, a module returns a table or a function (return function() ... end). - Settings one per line with an aligned trailing comment (
-- What it does (default: x)).
JavaScript / TypeScript
- TypeScript preferred,
strict, explicit types on parameters/returns/exports, noany;constby default,camelCasefunctions,PascalCaseclasses/types,UPPER_SNAKEconstants, 4 spaces, semicolons, double quotes. - Errors: throw
Errorsubclasses with a context message, never swallow them;async/awaitover raw promises. - Self-contained HTML pages: inline script in an IIFE with
"use strict"(like the html-doc templates).
Rust / Go / Java / C#
- Language conventions for naming (
rustfmt,gofmt, ...) but the user's spirit: explicit types on public items, early returns, errors propagated with context (Result+?with a message, Gofmt.Errorf("...: %w", err)), no panic/exit in libraries, constants named.
C
- Same layout as the C++ (
cpp-style/cpp-classsections, include guardNAME_Hwith its content indented, braces, spacing, include order and comments,(void)for an empty parameter list), the same file header as the C++ (XARTANIA banner, none or a text, percomments); a.his C when the project has no C++ sources. - Pointer on the type, like the C++:
char* buf,node_t* new_node(void);. - Names: functions, parameters, variables
snake_case;struct name_s/union name_u/enum name_ewith theirtypedef ... name_t;; enum values, macros and global constantsUPPER_SNAKE. - Functions return
OK/KO(or an error code /NULL) and test their pointer parameters before using them (if (!data || !input) return KO;first); a result is never ignored silently: use it, or(void)f(x);on purpose. - A function body stays under 40 lines of code (empty and comment lines not counted) and 4 nested control
blocks (
if/for/while/switch/do/else, a bare{ }is not a level): early returns, or an inner function. - C / C++ preprocessor: a conditional (
#if/#ifdef/#else/#endif) at the indentation of the code around it, its content one level more, one conditional per section of a header (cpp-style"Indentation & braces").
Assembly (NASM x86-64)
- NASM (Intel) syntax,
.asm(.s/.Sread as NASM; GAS files keep their own syntax). Everything lower case (mnemonics, registers, sizes, directives) except the constants. - File: the C / C++ header in
;comments, thenexternat the top, the sections in the order.data,.rodata,.bss,.text, theglobalright aftersection .text(one per line, each defined in the file, no unusedextern). - Indentation:
sectionand the function labels at column 0, their content at 4; a local label (.loop) at the level of its block and its content one level more, up to its last backward jump (a loop), else up to the next label; a comment line at the level of the code under it.
section .text
global my_strlen
my_strlen: ; in: rdi | out: rax
xor rax, rax
.loop:
cmp byte [rdi + rax], 0
je .end
inc rax
jmp .loop
.end:
ret
- Names: labels
snake_case, static functions (called, notglobal) prefixed by_(_my_helper), the global ones never (_startexcepted), the jump labels local (.name), data labelssnake_case(never a register name),equ/%define/%assign/%macroinUPPER_SNAKE. - Every function label carries the comment of its registers (
; in: rdi, rsi | out: rax); amov rax, Nbefore asyscallnames it (mov rax, 1 ; write); the trailing comments of consecutive lines on one column. - Functions: never fall through into the next one (end with
ret/jmp/ the exit syscall); a global function keepsrbx,rbp,r12-r15(System V:push/popthem); a stack frame (push rbp/mov rbp, rsp) only when the stack is used (push / pop,call,[rbp]/[rsp],sub rsp) and restored (pop rbp/leave) before everyret;xor reg, regrather thanmov reg, 0.
YAML / JSON / config
- YAML: 2 spaces (format constraint), keys
snake_caseor the tool's convention, GitHub workflows namedName - Kind (CI|CD), every step has aname:,set -e/set -euo pipefailin multi-linerun:. - JSON: 4 spaces, no trailing comma, keys
snake_case(or the format's convention).
Any other language
Follow the closest existing file of the project; otherwise the common rules above with the language's official formatter conventions, and say that no specific rule covers it.
Checking
xstyle (TsukiNi22/xstyle, 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)) checks the generic rules of every language (tabs, trailing
spaces, empty lines, indentation by 4, TODO tags) the C ones (C-*: names, x_s / x_t, pointers tested before use, ignored results, 40 lines, 4 levels), the
assembly ones (ASM-*: layout, names, declarations, ABI, stack frame, fall through, syscall names) and the Python /
shell ones (wildcard imports, bare except:,
type hints, print to stderr, open without encoding, shebang, set -euo pipefail, [[ ]]) and the Rust ones
(unwrap / panic! / todo! outside the tests, glob imports, naming, unsafe without // SAFETY:, errors on
stdout, dbg!): when it is installed,
run xstyle --rtk <paths> -r on the files written or reviewed, xstyle --rtk --fix for the fixable ones.
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| slack-gif-creatoranthropics/skillsKnowledge and utilities for creating animated GIFs optimized for Slack. Provides constraints, validation tools, and animation concepts. Use when users request animated GIFs for Slack like "make me a GIF of X doing Y for Slack." | Stars: 196k | Updated | Claude CodeCodex | Verified | Install |
| ponytailDietrichGebert/ponytailLazy senior dev mode for any coding task: the smallest change that fully solves it, and a reply a busy human understands in one read. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailHarvest every shortcut: comment into one debt ledger, so deferrals get tracked instead of forgotten. One-shot report. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |
| ponytail-debtDietrichGebert/ponytailList every `shortcut:` comment (and older `ponytail:` ones) as a debt ledger. One-shot report, changes nothing. Use for "ponytail debt", "what did ponytail defer", "list the shortcuts", /ponytail-debt. | Stars: 192k | Updated | Claude CodeCodex | Verified | Install |