Codebase Cleanup

Overview

Remove clutter while preserving all functional behavior. Cleanup only - no refactoring or redesign.

When to Use

• •Preparing code for production commit
• •Pre-merge cleanup passes
• •Removing accumulated debug artifacts
• •Dead code audits
• •Security and configuration reviews before release

When NOT to use: Refactoring, redesign, or functional improvements.

Core Principles

• •Be conservative. If unsure whether code is used, flag it instead of deleting.
• •Preserve git history readability. Group related changes logically.
• •Do not refactor working logic. Cleanup only.

Quick Reference

1. Dead Code Removal

Delete

• •Functions, classes, methods with no references
• •Commented-out code blocks (except those marked NOTE: or KEEP:)
• •Unused imports and dependencies
• •Unreachable code (after return, in impossible branches)

Flag for Review (Do Not Delete)

• •Code possibly invoked via decorators, reflection, or dynamic calls
• •Functions referenced only in tests
• •Any code you are <90% confident is safe to remove

2. Debug Artifact Cleanup

Remove

• •print(), console.log(), debugger statements
• •Hardcoded test values (e.g., user_id = 12345)
• •Temporary variable names: temp, test, debug, foo, xxx
• •Completed TODO / FIXME comments

Convert (Do Not Remove)

• •Useful debug output → structured logging with appropriate log levels

3. Code Organization

Import Order

1. •Standard library
2. •Third-party packages
3. •Local/project imports

(Separate groups with a blank line)

Remove

• •Duplicate code blocks (Flag if behavior differs slightly)
• •Redundant type annotations that add no clarity
• •Excessive blank lines (max two consecutive)

4. Documentation Audit

Remove

• •Comments that restate obvious code behavior
• •Outdated or misleading comments
• •Inline changelog notes (git handles history)

Keep

• •Explanations of why, not what
• •Warnings about non-obvious behavior
• •Links to issues, specs, or external references

Generate/Update

• •Add or update docstrings for public modules, classes, and functions
• •Follow project documentation standards

5. Security & Configuration Check

Verify Absence Of

• •Hardcoded credentials, API keys, tokens, or passwords
• •Internal URLs, IPs, or hostnames
• •Personal data or PII in fixtures

Confirm Presence Of

• •Environment variable usage for secrets
• •Proper .gitignore entries (logs, env files, caches, secrets)

6. Linting & Formatting Pass

After cleanup, run project-configured linters and formatters. Fix violations introduced by cleanup, but do not refactor functional logic.

General Approach

• •Run linters with project configuration
• •Apply safe auto-fixes
• •Flag any new rule suppressions added during cleanup
• •Fix violations caused by cleanup
• •Do not perform large-scale rewrites to satisfy linters

Python Example

ruff check --fix .          # Lint + auto-fix
ruff format .               # Format
isort .                     # Import sorting
pylint <modified_modules>   # Additional checks

JavaScript/TypeScript Example

eslint --fix .
prettier --write .

Linting Rules of Engagement

• •No new ignore comments (# noqa, // eslint-disable) without justification
• •If a lint rule conflicts with project style, flag rather than override

7. Execution Order

1. •Read and understand codebase structure
2. •Identify removal and modification candidates
3. •Apply changes file-by-file
4. •Update documentation (docstrings)
5. •Run linters and formatters
6. •Final verification: check references and run CI if available

8. Output Requirements

After completing cleanup, provide:

Summary

• •Total files reviewed
• •Files modified (brief description of changes)
• •Approximate lines removed

Flagged Items

Recommended Follow-ups

Improvements noticed but outside cleanup scope.

Common Mistakes