No Comments

---
name: no-comments
description: 'Edits code in a repo that bans prose comments: where a fact goes, which directives stay. Use when editing code or when the no-comments gate refuses.'
---
<!-- Generated by `basicly skills-build` from skill.yaml. Do not edit; edit the source. -->

# No comments in code

A code file carries no prose: no comment and no docstring. The code is the only source of
truth, so a change cannot leave a stale claim beside it. The `no-comments` hook refuses a
commit that adds prose.

## Rules

- **Put the fact where something checks it.** A comment is a claim that nothing checks.
- **Fix the code when it needs prose to say what it does.** Rename it, split it, or give
  the condition a name.
- **Do not write code that is harder to read.** A short name, a function with nine
  branches or a bare magic number has no comment to excuse it.
- **Keep each directive, with its code and a reason after it.** A tool reads the
  directive, and the reason is part of it.

## Where a fact goes

| The fact | Where it goes |
| --- | --- |
| A measurement: a count, a time, a rate | the commit message, and the issue or record of the change |
| What a function raises, changes or returns | a test that asserts it, and the type signature |
| What a bare `str` can hold | a type, an enum or a validator |
| Why this branch and not the other | a name for the condition, or a test named after the case |
| Which incident a guard exists for | the issue id in the commit message, and the test that reproduces it |
| What the module is for | its README, or the design document |
| A fact you cannot place | it was not necessary. Drop it. |

## Directives that stay

The gate never reports a directive, and `fix` never removes one:

`noqa` · `nosec` · `type: ignore` · `pragma: no cover` · `fmt: off` / `fmt: on` / `fmt: skip`
· a shebang · `eslint-disable` · `prettier-ignore` · `@ts-expect-error` · `@ts-nocheck`
· `stylelint-disable` · `go:build` · `CHECKSTYLE:` · `NOSONAR` · `SPDX-License-Identifier`
· a `/*!` licence banner · an HTML conditional comment.

## Commands

```sh
python3 .basicly/core/kit/comments/cli.py check <path>      # report; exit 1 when it finds prose
python3 .basicly/core/kit/comments/cli.py fix <path>        # remove the prose
python3 .basicly/core/kit/comments/cli.py languages         # each file extension it covers
```

- `check` never writes.
- `fix` writes only a change it can prove. A second strip must change nothing, and every
  string literal must stay. A Python file must parse to the same syntax tree.
- `fix` reports a file that it cannot read with certainty and leaves the file unchanged.

## Scope

YAML, TOML, JSON and Markdown keep their comments, because no code beside them is the
source of truth. The kit skips vendored directories such as `vendor` and `node_modules`.
Run `languages` for the current list.

## Transition existing code

Strict `no-comments` is the default and goal. When a repository explicitly selects
`[hooks.comments] policy = "no-comment-ratchet"`, leave unrelated legacy prose alone.
Add no new prose. The hook compares complete parsed comments and docstrings in HEAD
and the staged index. Rewritten or duplicated prose is new prose.

Run `basicly-comments ratchet` for the standalone Git-backed check. The existing
`check` command stays strict. Remove the transition setting once the repository has
no prose comments.