TsukiNi22/ai-utils / skills/python/python-comments
python-comments
VerifiedHow 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
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 5.8 KB |
| requires.txt | markdown | 19 B |
SKILL.md
View on GitHub---
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.
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: 319k | Updated | Claude CodeCodex | Verified | Install |
| requesting-code-reviewobra/superpowersUse when completing tasks, implementing major features, or before merging to verify work meets requirements | Stars: 319k | Updated | Claude CodeCodex | Verified | 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: 319k | Updated | Claude CodeCodex | Verified | 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: 319k | Updated | Claude CodeCodex | Verified | Install |