I'll Be Backspace

The comment linter that says what everybody's thinking.

---

Friend, Can We Talk About Your Comments?

Let me paint you a picture. You open a file. You're a busy person. And there, sitting on top of a two-line function like a wedding cake on a bicycle, is this:

# Sync pulls files; it does NOT recreate containers. That's enough for
# config a service reads live (Traefik file-watches dynamic/, Dashy
# re-reads conf.yml per request), but a compose change needs an `up` to
# take effect. Verified 2026-07-29: fixing postgres's data mount and
# force-syncing left the same container id running the old mount, so the
# crash loop continued. Hence the two-step below.
sync(service)
compose_up(service)

Six lines of comment. Two lines of code. Somewhere in there is one useful fact, and it is doing hard time.

Now — what if I told you there was a better way?

$ backspace deploy.py
deploy.py:2:5: error: comment-code-ratio: 6 comment lines describe 2 lines of code (ratio 3.0, max 1.5)
    2 | Sync pulls files; it does NOT recreate containers. That's enough for
    3 | config a service reads live (Traefik file-watches dynamic/, Dashy
      | ... 3 more lines
    7 | crash loop continued. Hence the two-step below.
      = help: A comment longer than the code it describes usually restates the
             code. Say what the code cannot.

1 file checked, 1 violation

That's it. That's the product. And folks, it is fast.

What's In The Box

• Nineteen languages out of the box. Python, Rust, Go, TypeScript, JavaScript, Bash, C/C++, Java, Kotlin, Swift, Ruby, PHP, Lua, SQL, YAML, TOML, HCL, Dockerfile, Makefile. Adding another is one TOML file.
• It knows a string from a comment. s = "# not a comment" does not fool it. Neither do raw strings, template literals, nested block comments, or JavaScript regex literals. This is the part everyone else gets wrong.
• Diff-aware. Point it at a mature repo and it won't hand you four hundred findings on code you didn't write. It checks what you touched.
• Docstrings are safe. Your API documentation is supposed to be long. We leave it alone unless you ask.
• A --json mode built for robots. Ships the offending comment text right in the payload, so your agent can fix it without opening the file again.
• Configurable six ways from Sunday, and — here's the kicker — a config show command that tells you which layer set every single value. No guessing. Never guessing.

Get It Installed. Right Now. Today.

Pre-commit — and this is where it really sings:

repos:
  - repo: https://github.com/phin-tech/ill-be-backspace
    rev: v0.1.3
    hooks:
      - id: backspace

Or any of these, whichever suits your operation:

$ uvx --from ill-be-backspace backspace   # try before you buy
$ pipx install ill-be-backspace           # a wheel, no Rust required
$ brew install phin-tech/tap/backspace

The package is ill-be-backspace; the command it installs is backspace.

Kick The Tires

$ backspace                       # current directory, changed lines only
$ backspace src/ --all            # the whole lot
$ backspace --diff=main           # everything your branch changed
$ backspace src/ --json           # for machines
$ backspace --stats               # who's the worst offender?

Exit codes are 0 clean, 1 violations, 2 you've configured something strange. Your CI will know exactly what to do.

Four Rules. That's All It Takes.

Rule	What it catches
block-too-long	More than max_lines (5) consecutive lines of comment.
comment-code-ratio	A comment longer than the code beneath it. This is the one that finds the real offenders.
comment-restates-code	A comment that only says what the code already says. Opt-in — see below.
banned-phrase	Words and regexes you pick — see below. There's an llm-tells preset for Verified 2026-…, Note that, it does NOT, and friends. Opt-in — we're not here to preach.

backspace explain <rule> if you want the long version.

Make It Yours

It reads config from wherever you already keep it — .backspace.toml, pyproject.toml, package.json, or Cargo.toml. No new file unless you want one.

max_lines = 5
exclude = ["**/vendor/**"]

[rules.banned-phrase]
preset = "llm-tells"

[languages.go]
max_lines = 8          # licence headers, we understand

[[overrides]]
paths = ["tests/**"]
max_lines = 15         # tests get a little room to breathe

The One-Line Essay

A block budget can't catch this, because it's one line:

# Set the user's name to the provided value if it is not None, otherwise keep the existing one.
user.name = name or user.name

max_line_words measures each line on its own:

max_line_words = 12

Twelve is not a number I made up. Across 907 real single-line comments, the median is 7 words and the 95th percentile is 12 — so this flags the top 3% and leaves everything else alone. Terse comments like # Cached: the upstream rate-limits at 10rps. sail straight through.

Just Show Me What I Wrote

Sometimes you don't want a verdict, you want a look. --audit lists every comment and always exits 0:

$ backspace --diff --audit
src/api.py:41 (line, 1 line, 18 words)
   41 | Set the user's name to the provided value if it is not None, otherwise…

src/api.py:58 (line, 2 lines, 9 words)
   58 | Retry once: the upstream 502s on cold start.
   59 | Anything longer and the client has already timed out.

1 file checked, 2 comments

Pair it with --json and hand it to your agent: "here is every comment you just added, go read them again." That's a review aid, not a gate — which is why it never fails a build.

The Comment That Says Nothing

Here's the one that goes right for the throat:

# increment the retry counter
retry_counter += 1

That comment has no job. comment-restates-code catches it by splitting the identifiers below into words — retry_counter becomes retry + counter — and measuring how much of the comment's vocabulary was already sitting there in the code.

Turn it on:

select = ["block-too-long", "comment-code-ratio", "comment-restates-code"]

[rules.comment-restates-code]
threshold = 0.8      # overlap at or above this counts as restating
min_words = 6        # shorter comments have too little to measure

It skips section banners, code samples and data shapes, because those name the code on purpose.

Why it's opt-in. A good "why" comment has to name the things it's talking about, so it picks up overlap honestly. Tuned against ~7,400 real files it fires about fifteen times, and a couple of those are arguable. It's a sharp tool with a real false-positive rate, not a safe default — which is why you have to ask for it.

Ban Your Own Words

Got a word you never want to see again? Put it in ~/.config/ill-be-backspace.toml and it follows you into every repo you touch:

[rules.banned-phrase]
words = ["substrate", "delve into", "leverage", "seamless", "robust"]

words are literal, not regexes — they're escaped for you, matched whole-word and case-insensitively. So substrate won't fire on substrates, and c++ is a word rather than a syntax error. If you want a regex, use extend = ['Verified \d{4}-\d{2}-\d{2}'].

Your Words Are Safe

Here's the important part. A project adds to your list, it does not replace it:

# some repo's .backspace.toml
[rules.banned-phrase]
words = ["synergy"]

You still get substrate, delve into, leverage, seamless, robust — plus synergy. The only thing that wipes your list is a project explicitly saying patterns = [...], which is the documented "start from scratch" switch.

key	takes	what it does
words	plain text	escaped, whole-word, case-insensitive — start here
extend	regex	appended to whatever's accumulated
patterns	regex	replaces the accumulated list
preset	"llm-tells"	the built-in bundle

Who Set What, And Where

Values stack up in this order, each one beating the last:

defaults → ~/.config/ill-be-backspace.toml → project config
         → [languages.*] → [[overrides]] → CLI flags → inline directives

Every layer only changes the keys it names. Set max_lines in a project and your personal require_suppression_reason still applies.

And when you can't remember why a value is what it is, just ask:

$ backspace config show src/api/handlers.py
src/api/handlers.py  (python)
  user config:    /Users/you/.config/ill-be-backspace.toml
  project config: .backspace.toml

  max_lines                  = 15            overrides[0]
  max_ratio                  = 1.50          default
  banned_phrases             = 6 pattern(s)  user config
  severity                   = error         command line

No guessing. Never guessing.

Full schema in skill/reference.md.

Sometimes The Long Comment Is Right

Wire formats. Protocol quirks. We're reasonable people:

# backspace: ignore[block-too-long] — frame layout is fixed by RFC 9114 §4.2

backspace: ignore for everything, backspace: ignore-file near the top of a file for the whole thing. Set require_suppression_reason = true and it'll insist you explain yourself — which, frankly, you should.

For The Robots

There's a Claude Code skill in skill/. Drop it in and your agent writes shorter comments in the first place, which beats catching them at commit time every day of the week:

$ cp -r skill ~/.claude/skills/backspace

Under The Hood

A clanker-rolled character state machine, one pass, no parser generators, no grammar downloads. Language definitions are plain TOML embedded at compile time — and you can add your own at runtime, same schema, no recompile.

Two things it's honest about: JavaScript regex-literal detection and Python docstring position are heuristics, not a parser. They're tested against the cases that matter and documented where they aren't perfect.

256 tests. It passes its own lint. We wouldn't dare ship it otherwise.

Contributing

New language? One file in languages/, one line in src/lang/mod.rs, a good_ and a bad_ fixture in tests/fixtures/. That's the whole ceremony.

$ cargo test
$ cargo run -- --all .

License

MIT. Go build something.