You know that sinking feeling. You open a file, scroll down, and there it is: a six-line comment explaining why the author used a workaround, a hack, a temporary fix that became permanent. The comment is apologetic, verbose, and full of justifications. And you know, deep down, that the code is wrong.
Bun, the fast JavaScript runtime, just codified that feeling into a rule. It’s a single line in a GitHub Actions config that tells Robobun—the bot that leaves automated comments on pull requests—to chastise itself if it writes a paragraph-long comment. The rule says: “If you need a paragraph-long comment to justify why the workaround is OK, the code is wrong — fix the code.”
Let that sink in. A bot is policing its own long-windedness based on a rule that is itself a comment. It’s a beautiful, recursive, deadpan joke. But it’s also a profound piece of engineering culture packed into one sentence.
Most people read this and laugh. They think it’s a clever gimmick about comment length. But it’s not. It’s a debt-accountability mechanism. It refuses to let documentation be the guilt-free excuse for leaving broken or temporary code in place. The moment you write a paragraph to justify a hack, you’re admitting the hack is a problem—and instead of fixing it, you’re passing the cognitive load to the next developer. The rule says: No. That’s not acceptable.
Think about the teams you’ve been on. How many times have you seen a comment like “// TODO: This is a hack because the API returns inconsistent data. We’ll fix it in v2.” And v2 never comes. The comment becomes a tombstone. The code rots. The comment becomes part of the landscape, a permanent crutch. A long comment is a confession of technical debt, not a documentation.
Bun’s rule flips that. It treats long comments not as a style issue but as a signal of avoidable complexity. If a workaround needs that much explanation, the code itself is the problem. The fix is to refactor the code, not to write a novel about it.
Now here’s the twist: the rule is enforced by the very kind of machinery it distrusts. It’s a comment that tells bots not to leave long comments. It’s an automated system policing another automated system. The irony is intentional. It’s a meta-norm: we’re using the tools we have to encode human judgment into the system. This is how culture becomes code. Good judgment isn’t just a value—it’s a feature you can ship.
For any engineer reading this, the lesson is immediate. Start looking at your long comments as liabilities. The next time you write more than three sentences to explain why something is the way it is, stop. Ask yourself: can I fix the code instead? Can I rename variables, break up the function, add a test, or delete the whole thing? If you can, do it. If you can’t, then maybe the comment is genuine—but more often than not, it’s a signal you’re ignoring.
Bun’s rule is a single line. It’s not a template or a guide. It’s a provocation. And it’s the kind of provocation that changes how you think about every line of code you write. The best rules aren’t about what you can’t do—they’re about what you should stop tolerating.
FAQ
Q: Isn't this rule just a joke? Does it really have practical value?
A: It's a joke with teeth. The humor makes it memorable, but the underlying principle is serious: long comments that justify workarounds are a sign of avoidable complexity. The rule forces teams to treat those comments as a defect, not a documentation opportunity.
Q: How can I apply this to my own team?
A: Start by flagging any comment longer than three sentences in code review. Ask the author: 'Can you fix the code instead?' If they can't, push for a refactor. If they can't refactor, then the comment is a genuine exception—but it should be rare. Turn it into a linting rule or a bot action like Bun did.
Q: What if a long comment is truly necessary for complex business logic?
A: If the logic is so complex that it requires a paragraph to explain, the code is likely too complex. Consider breaking it into smaller functions, adding tests that document behavior, or using a comment that points to external documentation. The exception proves the rule: if it's genuinely needed, it's a code smell you should still try to eliminate.