Leave the scar visible

In a billing service I maintained, a provider sometimes returned active for a subscription it had already cancelled. The workaround was six lines. My first comment began // provider is lying here, named the duplicate-charge risk, and linked the incident that proved it.

During review I softened the sentence to // normalize provider status because the original sounded unprofessional. I thought I had removed heat without removing information. Months later, a second caller reused the helper. Then a third.

The name normalizeSubscription made the function look like policy, while the polite comment omitted the fifteen-minute inconsistency that justified it. When I reopened the old diff, the sentence I had deleted explained the system faster than the abstraction we kept. Why did we make the lie sound respectable? We had polished the turd by improving its name while leaving the duplicate-charge path exactly where it was.

Angry programming is not permission to abuse people. It is permission to leave the violated assumption visible. Aim the anger at an impossible state, a broken vendor contract, a timer nobody can remove yet, or a schema the team regrets. You can stay perfectly civil in the review thread while the comment says the provider lies.

Here is the same workaround after two kinds of cleanup. The branch never changes.

// Normalize provider status for cancelled subscriptions.function normalizeSubscription(raw: ProviderSubscription) {  if (raw.status === "active" && raw.cancelledAt) {    return { ...raw, status: "cancelled" };  }  return raw;}

// HACK PAY-2187: provider can report "active" for 15 minutes// after cancellation, so trusting it can charge a customer twice.// Keep this quarantine local. Delete it when webhook revision 3// reaches every account and the PAY-2187 replay passes without it.function quarantinePay2187Status(raw: ProviderSubscription) {  if (raw.status === "active" && raw.cancelledAt) {    return { ...raw, status: "cancelled" };  }  return raw;}

The first version sounds reusable. Its professional tone changes how the reader classifies the code, even though it supplies no cause, customer risk, containment boundary, or removal event. The second version makes those facts difficult to miss. A future maintainer can object to the implementation without first excavating the incident from version control.

Professional wording can lie#

Google's official code review guidance says comments earn their place when they explain why code exists and carry reasoning the code cannot express. A tidy paraphrase of the branch fails that test. Anyone can read the condition already. The part the code cannot express is the provider's failure and the damage it can cause.

Once that context disappears, the patch changes category in the next reader's head. A local exception begins to look like a supported rule, and ordinary refactoring spreads it farther from the boundary that made it necessary.

Researchers call these explicit admissions self-admitted technical debt. One study examined 23.6 million code comments along with commit messages, issue sections, and pull-request sections across 103 open-source projects. Developers record suboptimal choices in all four places, which means a polished code comment can sever the closest explanation while the real confession drifts into a ticket nobody opens.

A separate study found 3,520 duplicate and near-duplicate debt comments across five Apache projects, and many same-root-cause groups lived outside regular code clones. I read that as a warning rather than proof of this exact spiral: debt language travels, and it can separate from the precise code that originally earned it.

Good codebases admit embarrassment#

Mature projects already leave blunt warnings in source when politeness would erase useful facts. A Linux hidraw sample labels a compatibility block an “ugly hack” for systems with stale userspace headers. The block also emits a compile-time warning telling distributors what to update. Its embarrassment points directly at the dependency and gives an operator somewhere to act.

CPython keeps a different kind of honesty in its email generator. An XXX comment admits that logic and tests disagree: an else seems necessary, yet the tests fail when it exists and pass when it does not. Rewriting that as “avoid duplicate newline” would invent a confident causal story the author did not have.

Both comments look embarrassing on purpose, and both preserve a causal edge for the next investigation — stale headers in one case, behavior its own author could not explain in the other. Nobody reading them has to pretend the workaround arrived through deliberate architecture.

Anger needs an address#

I haven't measured whether profanity makes a workaround disappear faster, and I doubt the swear word does useful work by itself. // FIXME this garbage gives no owner, cause, scope, or way out. The next person learns only that someone was upset.

Google's guidance for TODO comments asks for a bug reference or responsible person and, where possible, the event that will make the TODO removable. An angry comment can do better by carrying four coordinates:

• Broken assumption: webhook revision 2 reports active after cancellation.
• Consequence: billing may charge the same customer twice.
• Containment: only the provider adapter may rewrite this status.
• Exit: delete the branch after revision 3 ships and the replay passes.

Once those facts exist, blunt language helps the reader classify the code. Keep the incident and removal condition beside the branch so the workaround remains visibly abnormal. Research on on-hold self-admitted debt makes the exit condition operational: comments linked to external issues can be revisited when those issues close instead of waiting for somebody to remember the original compromise.

Make the code complain too#

A comment can be ignored, so angry programming moves the alarm into structure. Keep the workaround in the provider adapter, call it quarantinePay2187Status, increment a metric whenever it fires, and give the regression test the incident number. Exporting a generic normalizeSubscription helper would invite unrelated callers to depend on an accident.

The metric tells you whether the external failure still occurs. The import boundary keeps the patch from becoming a utility, while the test records the customer outcome rather than blessing every incidental line. If someone later proposes a shared normalizer, the ugly function name forces the review to reopen PAY-2187 before the exception spreads.

This is also why formatting cannot redeem the wrong abstraction. The Linux kernel's commenting guidance explicitly allows warnings about clever or ugly code and cautions that source-formatting tools do not fix bad programming. The patch underneath still has to be small and tested. What stays loud is the comment sitting on top of it.

After webhook revision 3 reaches every account, the next developer opens subscription.ts. The metric beside quarantinePay2187Status has read zero for a week, and the linked incident is closed. They delete twelve ugly lines, run the replay, and the test still passes.