25 Oct 2025
We often reach for comments when a piece of code doesn’t feel clear at first glance.
But in many cases, comments are only needed because the names aren’t doing their job.
When variables, functions, and modules are named thoughtfully, code can explain itself.
Let names speak the intent
The second version instantly communicates what the value represents and why it exists.
Good naming reduces friction for you and everyone who touches your code later.
Short or abstract names make readers pause to decode them:
❌ // Duration in milliseconds for how long a toast stays visible const t = 3000; ✅ const toastDisplayDurationMs = 3000;
❌ // Convert to Celsius function calc(v) { return (v - 32) * 0.5556; } ✅ function fahrenheitToCelsius(fahrenheit) { return (fahrenheit - 32) * 0.5556; }
Prefer Boolean Names With is / has / can
When naming booleans, choose names that answer a yes/no question:
❌ let active = true; ✅ let isActive = true;
Other useful prefixes:
- is → state
- has → possession/capability
- can → permission/ability
- should → recommendation/intention
Use comments for context, not translation
Sometimes comments are necessary. But not to restate what the code already says.
Use comments when explaining:
- business rules that aren’t obvious
- edge cases that took time to discover
- reasons for a technical decision
- limitations you can’t control
Code is read far more often than it’s written.
Naming is about communicating intent to other developers.
Make reading effortless.
Let your code explain itself.