Skip to content

TsukiNi22/ai-utils / skills/python/python-comments

python-comments

Unverified

How 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 def of a script: the behavior in a trailing comment of the def line (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.py too ("""\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 :param docstrings 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-TODO of xstyle): describe the limitation in a normal comment.
  • pass # Nothing is never written: pass alone 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.

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