Removing Dead Code

Deleting code is cheap to do and cheap to revert only when each deletion is atomic and carries its proof. Static tools produce candidates. What counts as proof depends on the category, and the procedure below is ordered by how much proof each category needs. Never skip ahead: a module that "looks dead" to an analyzer is a candidate, and a candidate is not a deletion.

This file is language-neutral. Tools, exact commands, version pins and the language's own dynamic-reference traps live in one reference per language:

RELATED: porting-py2-to-py3 (when the cleanup prepares a Python 2 code base for the port).

Before you start

1. Read references/<language>.md for the code base's language. If it does not exist, say so and proceed with the tool categories below.
2. Run the full test suite and record the result. Freeze the installed dependency set and the lockfile. A project without a lockfile records the installed set and the fact that no lock exists; that is a baseline, not a missing step. Every later step compares against this.
3. Start dynamic collection now, even if today's PR only removes imports. Categories 4 and 5 need 30 to 90 days of production data, and the clock only starts when the collector is deployed. When the collector cannot be wired (no common entry point in this repo, no deploy path), the minimum is a tombstone in each suspect with the window end date in the commit message.
4. Deploy manifests often live in another repository (container files, process-manager files, CronJob YAML, CI). Search them there (gh search code), or name the check as a merge gate in the commit message. Never assume they are empty because this checkout has none.
5. Static analysis cannot prove an endpoint, a job, a task or a whole module dead. Read the "Dynamic evidence" section before any claim about those.

Tool categories

Every language has an equivalent of each row. Pick the one for the code base and write its name and version in the commit messages.

The procedure, ordered by proof required

Work through the categories in order. Each category lists what to find, the tool category, the proof required before deleting, and what to preserve.

1. Unused imports and unused local variables

Read the list before applying the autofix. An import that only has effects on import is not unused. Suppress the rule on that line with a one-line reason. In languages where an unused import is a compile error, this category is "it builds" and needs no linter.

2. Unreachable code

3. Unreferenced private functions, classes and methods

git grep -n -w 'export_rows'
gh search code 'export_rows' --owner <org>
git log -S 'export_rows' --oneline | head

If a symbol is only called by another dead symbol, delete both in the same commit. "No reference found in the analyzed files" is a candidate, never a proof. The exception is a compiled language with no name-based function lookup and a whole-program reachability analyzer: for unexported symbols its report is proof on its own, once build tags, linker directives, FFI exports and plugin lookups have been checked.

4. Whole modules

Dynamic evidence is mandatory here. If collection has not run for the full window yet, the module stays and the commit message of the collector PR says when the window ends.

5. Public but unhit endpoints, tasks and cron jobs

The soak is not optional. A route with zero hits in 30 days and a quarterly report job look identical in the logs.

6. Unused dependencies

Regenerate the lockfile in the same commit and delete the transitive packages that vanish from it. A dependency removed from the manifest but still pinned in the lock is not removed. Without a lockfile, list the orphaned transitives by name in the commit message (from the dependency tree tool). The staging run is a merge gate, not a pre-commit gate: the commit carries the uninstall and the suite result and names the staging run as the condition for merging. Also trim unused extras and tiny libraries that 20 lines of the standard library replace.

7. Database columns and tables

Out of scope for this skill. Removing a column is expand/contract: stop reading it, deploy, confirm with the database's table statistics or query logs, then drop in a later release. Never bundle schema drops with code deletion.

Commit rules

1. One removal per commit, with the proof in the message. A category with fourteen items is fourteen commits, or one commit per module when the items are mechanical and the tool output is attached.
2. Delete, never comment out. git log -S name finds it again.
3. Tests that only exercise the deleted code go in the same commit. A test that fails after the deletion is either proof the code was alive or a test to delete; decide, do not skip it.
4. Full suite after every batch, not only at the end of the PR.
5. Soak between batches. Deploy, watch error rates and 404/500 counts on the neighboring routes, then open the next batch.
6. Rarely hit error paths are not dead. Zero hits on an error handler is good news, not a deletion candidate.

Message shape, one per category. The names are illustrative; in your repo the same names may be alive through a string path, so run the ladder before copying the shape:

Remove unused imports from billing/ (<linter> <version>)

Full suite green (2143 passed). Kept billing package re-exports and the
billing.signals side-effect import.

Remove legacy_export._format_row and _escape_cell

<analyzer> lowest tier, no references: git grep -w across code, templates and
infra repos, gh search code in the org. legacy_export has no reflection or
string dispatch. Deleted the test that only covered _format_row in the same
commit.

Remove /v1/legacy/export route and legacy_export module

0 hits in access logs 2025-10-01..2026-10-01. 0 executed lines in production
coverage across api, 50 workers and 90 cron jobs (2026-07-01..2026-10-01).
Absent from every schedule. Finance confirmed the CSV export was retired in
2024. 410 flag soaked 2026-09-01..2026-10-01 without a hit.

Dynamic-reference risk checklist

Search for each of these before deleting a name. Any hit moves the item up one category in the proof ladder. The language reference lists the concrete spellings.

• Reflection and name-based lookup: attribute access by string, global or module lookup by name, dynamic import with a non-literal or config-driven string
• Task-queue names: tasks registered or dispatched by string, beat and cron schedules
• Template references: route names, helpers, filters, macros and context processors called from templates
• Public export lists and package index re-exports
• Entry points and plugin registries declared in the package manifest
• Migrations that import models or helpers
• Serialized class paths in caches, queues and sessions: removing the class breaks deserialization of data already stored
• Signal and event listeners registered only by importing the module
• RPC, webhook, admin command and management command names
• External consumers: other repos, SDKs, partners, mobile clients
• Jobs that run yearly, quarterly or at month end
• Code behind a feature flag that is currently off

A hit is an entry point, schedule or lookup that can select the name. A suggestive name alone ("monthly", "legacy", "v1") is a prompt to check the schedules, not a hit; a schedule entry or an open-ended dispatch is.

Dynamic evidence

Four techniques, from cheapest to strongest, and what each proves:

Prune the candidate list with proof of life, prove the deletion with coverage or a tombstone. Cost depends on the runtime: interpreted languages pay a tracer, compiled languages often ship binary coverage at near-zero overhead; the language reference says which.

Multi-service production coverage

When one code base ships as many services (one API plus dozens of worker Deployments and CronJobs), only the union of coverage across all of them proves a function dead. A function unhit by the API is routinely hit by a cron job. The design is the same in every language:

1. Collection in process, started at the common entry point after the process has forked, writing one data file per process with a unique suffix.
2. Persistence on exit, on SIGTERM and on a periodic timer for long-running workers, then upload to a bucket keyed by service and pod.
3. Sampling: one replica per Deployment, every CronJob run, since short jobs have no steady state.
4. Combination by a daily job that merges every file, then joins executed lines against the list of function definitions to emit zero-hit functions per service and in total.
5. Window and seasonality: cross the window with every schedule; a job that did not run in the window leaves its code "unknown", not "dead".
6. Output: a candidate list with the proof attached (services, window, hits = 0) that becomes the commit message of the removal.

Quick reference

Common mistakes

• Deleting on the analyzer's lowest tier alone. It reports "no reference found", which templates, strings and other repos routinely contradict.
• Running a tool on syntax it cannot parse. It reports nothing, or crashes, and "nothing found" reads as "nothing unused". Check the language reference for parser limits (Python 2 source is the common case).
• One big commit per category. Reverting a single wrong deletion then means reverting the whole PR.
• Proof in the PR description only. The description does not survive a squash merge or a cherry-pick. The commit message does.
• Treating test coverage as production evidence. Test coverage shows what tests reach. Code that only tests call is still dead code, and code tests never reach may be hot in production.
• Collecting production coverage from one service only. The API is one of many entry points. Combine all services before concluding anything.
• Starting the window too late. Dynamic collection should start in the first PR, before any module or endpoint deletion is even proposed.
• Removing a dependency without regenerating the lock. Transitive packages stay pinned and the "removal" changes nothing in the image.
• Deleting the flag and the code in one step. Keep the 410 or raise behind a flag for one cycle first. Flipping the flag back is the rollback.
• Deleting a class that is serialized somewhere. Queues, caches and sessions hold instances; deserialization fails after the deletion.

Checklist

Before declaring a removal batch done:

• Language reference read, or its absence stated and the chosen tools named
• Baseline suite result, installed set and lockfile recorded before any change
• Dynamic collection deployed and the window end date written down
• Each deletion is its own commit, with the proof and the tool version in the message
• Every deleted name searched across code, templates, config and sibling repos
• The dynamic-reference checklist walked for every deleted name
• Endpoints and jobs: logs, schedules, consumers and soak all documented
• Dependencies: lock regenerated, orphaned transitives removed, staging run green
• Tests that only exercised deleted code removed in the same commit
• Full suite green after the batch
• Soak period scheduled before the next batch