TsukiNi22/ai-utils / skills/python/python-comments
python-comments
UnverifiedHow Tsukini writes comments in Python - the Python equivalent of cpp-comments, from his scripts (libutils cmake/scripts, MAGIC) - the Xartania header (63 double quotes), the
Tsukini comment style (Python)
<name> (a skill) = the folder of that skill: ~/.claude/skills/<name> (setup.sh) or ${CLAUDE_SKILL_DIR}/../../*/<name> (plugin of the marketplace).
Always in English, short, no final period. Comment the why and the non-obvious, never paraphrase the code.
General rules of every language: comments (section 1). Code style: python-style. When a file already has its own
comment style (an older file of MAGIC with """ Import """ banners), the local style wins.
1. Structure comments (exact strings)
- File header:
python3 <cpp-class>/scripts/header.py --file <name>.py --desc "..."(63", banner,Edition:/File Name:/File Description:with##lines), never written by hand. - Section banners, at column 0, one empty line before:
##### Import #####,##### Const #####,##### Tools #####,##### Class #####,##### Program #####,##### Declaration #####,##### Tests #####(only the used ones). - Import labels (exact):
# Import that can't be in the try,# Import that can be checked; the optional install block# Try to install dependencies (failsafe); the guard comments# Check if the program is call and not imported/# Check if the program is imported and not call(the user's wording, kept as is).
2. Trailing comments (the most used)
from pathlib import Path # Used to create & edit files and to get the file name
exit(255) # Special exit code (only place used)
data = {} # {code: [message, info, restriction], ...}
FATAL: int = 0b1000 # Global error, the whole execution stops (100% execution stop)
LOCAL: int = 0b100 # Local error, the local execution probably stops (some chance of execution stop)
SIZE_MAX: int = 2**64 - 1 # size_t max on 64 bits machine
- Every checked import:
# Used for <what>/# Used to <do what>. - Constants: meaning, unit, values (
0 = unlimited), the shape of a container ({code: [message, info], ...},<id, name>for a tuple), alternatives with|(# dark | light), precisions in(...); aligned in a group of constants (fields and comments in columns). - Private / free functions and the
defof a script: the behavior in a trailing comment of thedefline (def _parse(self, line: str) -> int: # one device value). - Danger in upper case:
# DOES NOT CLOSE THE PORT!!!,(only!).
3. Block comments above the code
# Init the loading overlay
loading = LoadingOverlay(window, ...)
# Wait until at least one device have been found or timeout
while time() - start <= timeout and not card.values:
One line, upper case first letter, no final period, describes the intent of the block, an empty line before the block.
word: precision form for a nuance (# Not an error: the port can be closed by the user). Small labels in lower case
are fine for the parts of a block (# code, # message, # info in a loop building several strings).
4. Docstrings (rare, short)
class Parameters:
"""
Class to handle the parameters edition / reading
"""
def get_parameter(self, name: str) -> str | None:
"""
Get the value of a parameter
"""
- Classes and public methods only: one or two lines, the text indented by 4 more than the quotes (8 spaces inside
a class), the quotes alone on their lines. Frozen dataclasses of
const.pytoo ("""\n Return values\n """). - Never Sphinx / Google / NumPy fields (
:param x:,Args:,Returns:): the types are in the signature, the meaning of a parameter goes in its name or a trailing comment. MAGIC's older:paramdocstrings are not reproduced. - Scripts: no module docstring (the header is the description), no docstring on the functions.
5. Misc
- Disabled code kept only when it is a real alternative, with
#and no space (#&& dnf remove -y gnupg2). - No
TODO/FIXME(G-TODOof xstyle): describe the limitation in a normal comment. pass # Nothingis never written:passalone is the empty body.
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 PY,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 |
|---|---|---|---|---|---|
| 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 implementation | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| 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 fallback | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |
| 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 always | Stars: 318k | Updated | Claude CodeCodex | Unverified | Install |