Common Bugs with Comments
Yes, comments cause bugs too — here are five real ways.
From Bee: "I see this exact bug in beginners every week. Read it once, and you'll spot it on yourself before it bites."
Comments that lie
js
// returns the user's age in years
function getAge(user) { return user.birthDate; }⚠️
Why this happens
The comment hasn't kept up with the code. New readers trust the comment and waste time.✅
The fix
When you change the code, change the comment in the same commit. Or delete the comment.Commented-out code that confuses readers
js
// const oldLogic = computeOld(x);
const result = computeNew(x);
// if (oldLogic !== result) ...⚠️
Why this happens
Future readers wonder what the comments mean. Are they an in-progress migration? Are they safe to delete?✅
The fix
Use git to recover deleted code. Don't leave commented-out blocks for "just in case."Doc comment with wrong @param types
js
/**
* @param {number} age
*/
function f(age) { return age + 1; }
// Called with f("5") → returns "51"⚠️
Why this happens
The JSDoc says number but the code accepts anything.✅
The fix
Either use TypeScript (enforced types), or add an explicit type check inside the function.Magic-comment typos that disable tools
js
// eslint-disabled-next-line ← misspelled, has no effect
const x = veryDodgyCode();⚠️
Why this happens
Tools silently ignore unrecognized magic comments.✅
The fix
Copy-paste the exact directive from the tool's docs. Editors should highlight valid ones.TODO comments that never get done
js
// TODO: validate this before launch
function submit(data) { send(data); } // 3 years later, still no validation⚠️
Why this happens
TODOs accumulate. Many are forgotten and shipped to production.✅
The fix
Audit TODOs quarterly. Convert real ones into tracked tickets; delete the rest.💡
Want the full lesson?
Read Comments — the complete lesson, or test yourself with the quiz.