Skip to content

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

python-comments

Verified

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

FileKindSize
SKILL.mdskill md5.8 KB
requires.txtmarkdown19 B
---
name: python-comments
description: 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 ##### Section ##### banners, the "# Import that can't be in the try" / "# Import that can be checked" labels, the "# Used for ..." trailing comment of every import, trailing comments on constants (meaning, unit, values, aligned in a group), block comments above the code, short indented docstrings for classes and public methods, no Sphinx / Google docstrings, notations and tone. Use whenever adding, rewriting or reviewing comments or docstrings in Python code for the user, or when generating Python code that needs comments.
metadata:
  summary: 'Python equivalent of `cpp-comments`: `##### Section #####` banners, import labels, a `# Used for` on every import, aligned trailing comments, block comments, short indented docstrings, never Sphinx fields.'
---

# 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)
```python
    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
```python
    # 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)
```python
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](https://tsukini22.github.io/my-universe/), sources: [TsukiNi22/xstyle](https://github.com/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: 319kUpdated Claude CodeCodexVerifiedInstall
requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirementsStars: 319kUpdated Claude CodeCodexVerifiedInstall
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: 319kUpdated Claude CodeCodexVerifiedInstall
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: 319kUpdated Claude CodeCodexVerifiedInstall