Przejdź do treści
Biblioteka skilli
Programowanie · Pisanie

update-docstrings

/update-docstrings

Dopisuje i poprawia docstringi oraz komentarze w plikach źródłowych, w dowolnym języku, na przykład NumPy lub TSDoc.

Repozytorium
loom ↗
Licencja
Apache-2.0
Ostatnia zmiana repozytorium
27.10.2026

Ocena i bezpieczeństwo

100/ 100Klasa: dobry
Format25 / 25
Frontmatter z nazwą i opisem, poprawna nazwa, opis do 1024 znaków, nazwa zgodna z folderem.
Odkrywalność25 / 25
Opis mówi, kiedy użyć skilla, ma sensowną długość i jest w 3. osobie.
Treść35 / 35
Co najmniej 150 słów i do 500 linii, nagłówki, listy kroków, przykłady albo kod.
Higiena15 / 15
Bez zaślepek typu TODO, bez ścieżek Windows, z licencją.
Ryzykobrak sygnałów w skanie
Pliki w paczce
5
Skrypty
0
Komentarze HTML
0
Adresy URL w SKILL.md
0
Przestarzałość

Brak sygnałów. Repozytorium zmienione 27.10.2026, bez odwołań do wycofanych modeli i API.

Licencja

Apache-2.0, otwarta: można używać i zmieniać, z zachowaniem licencji i informacji o zmianach.

Co robi i kiedy

Dopisuje i poprawia docstringi oraz komentarze w plikach źródłowych, w dowolnym języku, na przykład NumPy lub TSDoc.

Oryginalny opis (EN)

Add or update docstrings, doc comments, and inline comments in source code — any language. Use when the user wants docstrings written or fixed, a conversion to a doc style (NumPy, TSDoc, rustdoc), or a comment cleanup. Source files only — README/ADR/prose docs belong to write-documentation / write-readme.

Jak działa

  1. Foundational principle: self-contained
  2. Public vs internal
  3. Language dialects
  4. Comments
  5. Workflow
Sekcje z nagłówków SKILL.md, w oryginale · 78 linii, 1 351 słów
Podgląd SKILL.md
---
name: update-docstrings
description: Add or update docstrings, doc comments, and inline comments in source code — any language. Use when the user wants docstrings written or fixed, a conversion to a doc style (NumPy, TSDoc, rustdoc), or a comment cleanup. Source files only — README/ADR/prose docs belong to write-documentation / write-readme.
---

# Update Docstrings

"Docstring" below means the language's doc unit, whatever its syntax: a Python `"""` string, a TSDoc `/** */` block, a Rust `///` comment.

**Docs-only diff.** The diff this skill produces changes docstrings and comments, never code — not a signature, not an import, not a blank line inside a body. When the real fix is code — a rename, an extracted helper, a lambda promoted to a named function so it can carry a doc — propose the change and let the user decide; don't make it while "just adding docstrings".

## Foundational principle: self-contained

Every docstring is read by a first-time reader: someone with the source in front of them and nothing else — no PR thread, no tracker, no design docs, no memory of the project's history. A docstring is **self-contained** when it gives that reader everything, in place. Four rules follow:

- **Presence never lapses.** Everything gets a docstring — public and private, trivial and complex; only length scales with the symbol's surface. A construct that syntactically cannot carry one (a `lambda`, an inline callback) needs promoting to a named symbol if it needs explaining — a code change, so propose it.
- **Forward-facing: behaviour, not process.** Write for the reader who arrives after the dust has settled; say what the code does today. "Phase 0", "stub until issue 3", "for now", "lands in issue 2", sprint labels, PRD/ticket links — process narrative rots and means nothing to a first-time reader; it belongs in the PR description or the tracker.
- **State the rule, not the citation.** No "ADR-0019", "per the RFC", "as the design doc says", plan/PRD titles, or issue IDs. The decision may well _live_ in an ADR — that is correct, and it is exactly why the docstring must not point at it: the reader cannot open ADR-0019 from the source. Write the rule the code follows, in plain terms. Bad: `the stable ADR-0019 token path`. Good: `the stable token path; sibling ids are independent, so an unrelated add or delete never renumbers a node`. The only names a docstring may carry are code symbols the reader can resolve in the same codebase (a class, a function, a config key).
- **Gloss project jargon at first use.** The first time a domain term appears in a file, give it a one-line gloss — `a "ksub" (kabelsubgroep) is a bundle of cable segments owned by one transformer` — then use it freely; the reader can grep back to the definition.

**Register:** invoke the `write-simply` skill (via the Skill tool) — every docstring and comment follows its register. Mood still follows the dialect.

## Public vs internal

| Symbol kind                                                                                   | Treatment                                                                                                                          |
| --------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Public** — part of the module's API surface (the language reference names the exact signal) | Full docstring in the language's dialect: summary + extended description as needed + parameter / return / error / example sections |
| **Internal** — private by the language's convention                                           | One sentence, plus at most one more on _how_ it works when non-obvious. No parameter / return sections.                            |

The split is about _length_, never _presence_. Full sections on a tiny private helper just restate the signature the reader can already see; one line of intent is what they actually need. Reaching for a parameter section on an internal helper means either the symbol isn't actually internal, or the docstring needs trimming back down.

### Section rules — every dialect

- **Summary**: one line, concrete ("Split a dotted Capability ID into three segments", not "Implements parsing logic for identifiers"), ending with a period. Mood (imperative vs third person) follows the dialect. A summary that only re-says the symbol's name fails — "Gets the name" on `get_name` documents nothing; say what the signature can't.
- **Extended description**: only when the summary needs context — invariants, side effects, or why the symbol exists. Skip for obvious functions.
- **Parameters**: describe _meaning_, not the type the signature already shows.
- **Returns**: what the value _is_. Omit for procedures that return nothing.
- **Errors / Raises / Throws**: failures raised _deliberately_ — not every error reachable through the call graph, and not errors that fire only when the caller breaks a contract the docstring already states.
- **Name constants, don't copy values**: `within STALE_THRESHOLD_SECS`, not "within 5 minutes" — the copied value silently rots when the constant changes. Glossing a literal's unit in place (`1048576` is 1 MiB) is fine; that adds clarity, not a second copy.
- **Examples**: when usage is non-obvious, with real values from the codebase, not placeholders. Prefer the dialect's executable form — an executable example doubles as a smoke test.

## Language dialects

Read the file's language reference before writing — it carries the public/internal signal, section syntax, special cases, and the doc linter:

- **Python** — NumPy style: [references/python.md](references/python.md)
- **TypeScript / JavaScript** — TSDoc: [references/typescript.md](references/typescript.md)
- **Rust** — rustdoc: [references/rust.md](references/rust.md)

No reference for the language? Apply everything above through its dominant convention (javadoc, godoc, XML doc comments, …): same presence rule, same public/internal split, sections in the shape that convention renders.

## Comments

A comment is prose too, and self-contained applies unchanged: behaviour not process, the rule not the citation.

What differs from a docstring is the bias. A docstring's presence never lapses; a comment's must be earned. The code already says _what_ it does — a comment earns its place only by saying _why_: a non-obvious decision, a workaround for an external bug, an invariant the code leans on, an ordering that looks arbitrary but isn't.

The test is altitude. A comment at the same level of abstraction as the code restates it — delete. A comment earns its keep by moving **lower** — precision the code can't show: units, boundary inclusivity, who owns a resource, what null means — or **higher** — the intuition: the why, or the simpler mental model behind the mechanism.

Delete on sight:

- **Commented-out code** — version control remembers it; a dead block in source is noise.
- **Restatement** — `# increment i` above `i += 1`, `// loop over the rows` above the loop. If the comment only re-says the line below it, cut it.
- **Decorative banners and dividers** — `# ---- helpers ----`, `// === main ===`.
- **Doubts and notes-to-self** — `# TODO: this is probably wrong`, `// not sure why this works`. An actionable TODO belongs in the issue tracker with an owner; a vague doubt belongs nowhere.

Keep, but rewrite to forward-facing prose:

- A comment that explains _why_ non-obvious code is the way it is. Strip any process narrative or document citation, apply the writing skill, and leave the bare reason.

If a comment exists only to decode a cryptic name or untangle a confusing line, the fix is the code, not the comment — a rename or an extract. That's a code change: propose it per the docs-only rule rather than refactoring silently.

## Workflow

1. Invoke the `write-simply` skill (via the Skill tool) — every docstring and comment is prose under its rules; Strunk's composition rules and the AI-pattern catalogue live there, not duplicated here.
2. Detect the language; read its reference above (or pick the dominant convention).
3. Read the file end-to-end — the bodies, not just the existing docs; mark which symbols are public vs internal.
4. Write in source order — public symbols first in long files, then internal.
5. Re-read each docstring against the body; where they disagree, **the code wins** — rewrite the doc to what the code does today. Then check each is self-contained. When rewriting, preserve modality — _must_, _should_, and _may_ state different obligations; don't swap one for another unless the code says so.
6. Pass over the comments per the Comments section: apply the delete-on-sight list; rewrite survivors to forward-facing prose.
7. Run the doc linter named in the language reference and fix what it flags. Done when every symbol carries a docstring, no remaining comment matches the delete-on-sight list, every survivor states a _why_, and the linter is clean.
Pliki w paczce (5)
  • SKILL.md 9 KB
  • deps.yml 1 KB
  • references/python.md 5 KB
  • references/rust.md 3 KB
  • references/typescript.md 4 KB

Wersje

W bazie nie ma innych skilli o nazwie update-docstrings.

Migawka bazy z 13.11.2026 · wersja paczki 505cd782e02b (skrót SHA-256 całej paczki)

Pobrania w ostatnich 30 dniach: 0 · ranking

Zgłoś problem z tym skillem: szkodliwa treść, błędny opis albo prośba autora o usunięcie.

Podobne skille

  • 95code-comments
    Ustala zasady pisania komentarzy w kodzie: wbudowane, dokumentacyjne (TSDoc, GoDoc, docstringi) i TODO, także przy przeglądzie diffów.
  • 100doc-gen
    Generuje dokumentację z kodu źródłowego: docstringi, pliki README i referencje API.
  • 100documentation-generation
    Generuje dokumentację projektu: README, docstringi (JSDoc, JavaDoc, Python), opisy OpenAPI i potoki dokumentacji w CI/CD.
  • 100write-docstrings
    Pisze i sprawdza docstringi w repozytorium, gdy trzeba dodać nowe, przejrzeć istniejące albo je zmienić.
  • 100configure-docs
    Konfiguruje dokumentację kodu (TSDoc, JSDoc, pydoc, rustdoc, TypeDoc, MkDocs, Sphinx): docstringi, generator dokumentacji i wymuszanie pokrycia dokumentacją w CI.
  • 100docs-writer
    Pisze README, komentarze w kodzie, ADR, wpisy do CHANGELOG i poradniki API na podstawie kodu, z przykładami, które faktycznie działają.

Uwagi i zgłoszenia

Wiadomość trafi do Bartosza Sokolińskiego. Adres e-mail jest potrzebny tylko do odpowiedzi. Szczegóły w polityce prywatności.