Commented-out Code

ID

python.commented_out_code

Severity

low

Remediation Complexity

medium

Remediation Risk

low

Remediation Effort

medium

Resource

Code Smell

Language

Python

Tags

code-style, dead-code

Description

Reports #-style comments whose contents look like Python code (starts with a keyword like if, for, def; or contains an assignment / call that looks like a real statement). Commented-out code accumulates as dead weight and grows stale; version control already tracks the deleted history.

# if x > 0:                  # FLAW
# value = compute(x)         # FLAW
# for item in items:         # FLAW

# TODO: implement this       # OK — prose comment
# explanation: see #1234     # OK — explanation

Rationale

Comments that contain code drift away from the code they shadow: the syntax becomes invalid, names are renamed, and the comment ends up describing something that no longer exists. Either the lines should be deleted (their history is in git) or, if they are reference material, they should be moved into a docstring or a real test.

The rule is intentionally conservative — it requires both a keyword-or-call shape and balanced parentheses, and ignores common comment markers (# noqa, # type:, # TODO, …​) so prose comments do not trip it.

Remediation

Delete the lines. The commit history preserves them. If the lines are reference material (e.g., an alternative implementation kept for later), move them into a docstring or a separate experiments.py so they are not silently rotting next to the live code.

References