Prefer Deleting Code Over Commenting It Out
Commented-out code is a museum exhibit nobody asked for. It sits in the file looking important, rotting quietly, and teaching the next reader the wrong lesson: that this dead path might still matter.
Git already remembers. That unused helper from last Tuesday is in history. You can get it back in a checkout or a git show. What you cannot get back is the clarity of a file that only contains what is alive.
I used to leave big blocks of commented code "just in case." The case never came. What did come was a teammate asking whether those lines were meant to be restored, and a PR review where half the discussion was about code that was not running.
A better default:
- Delete the dead path.
- If you might need the idea later, write a one-line note in the PR or a short ticket — not a fifty-line fossil in the source.
- If the behavior is subtle, add a test that locks in the intended behavior instead of preserving the old implementation as a comment.
There are rare exceptions. A two-line alternative you are A/B comparing in the same PR can stay commented for a day. A vendor workaround with a ticket link might earn a short comment explaining why the weird call exists. Those are annotations, not archives.
The rule of thumb I use: if the comment is longer than the explanation of why the live code is correct, delete the comment and keep the explanation (or a test).
Your codebase is not a attic. Treat it like a workshop. Tools on the bench. History in version control. And nothing pretending to be useful when it is not.