Code Smell 02 - Constants and Magic Numbers
Maximiliano Contieri
Engineering Manager@Avature | CS Teacher@UBA | Book Author@O'Reilly | MaximilianoContieri.com
A method makes calculations with lots of numbers without describing their semantics
TL;DR: Avoid Magic numbers without explanation. You don't know their source and are very afraid of changing them.
Problems 😔
Low testability
Low readability
Solutions 😃
1) Rename the constant to a meaningful, intention-revealing name.
2) Replace constants with parameters, so you can mock them from the outside.
3) The constant definition is often a different object than the constant (ab)user.
Refactorings ⚙️
Examples
Algorithms Hyper Parameters
Context 💬
Magic numbers are literal values embedded directly into your code without explanation.
They often appear in algorithms, configuration rules, or business logic as unexplained numeric values.
At first, they might feel faster to write, but over time they turn into hidden assumptions that no one remembers.
Future maintainers must guess their meaning, increasing the risk of errors when the values need to change.
Constants help, but naming them meaningfully and placing them in the right context is what turns a magic number into a reliable, self-explanatory part of your code.
Sample Code 📖
Wrong 🚫
Right 👉
Detection 🔍
Many linters can detect number literals in attributes and methods.
Tags 🏷️
Declarative Code
Level 🔋
[X] Beginner
Why the Bijection Is Important 🗺️
When you replace a magic number with a named constant, you create a bijection between the value and its meaning.
This one-to-one relationship ensures every numeric value has a clear, unambiguous purpose in your system.
Without it, the same number could be reused for different reasons, leading to confusion and accidental coupling.
A bijection between meaning and value makes the code easier to navigate, test, and evolve without fear of breaking unrelated parts.
AI Generation 🤖
Large Language Models can introduce magic numbers when generating code, especially in examples or algorithm implementations.
Treat AI-generated values with the same suspicion you would any human-written literal.
Always check if the number is a placeholder, a real-world constant, or an algorithmic parameter, and replace it with a meaningful name before merging it into production code.
AI Detection 🥃
Code reviewers should stay alert to magic numbers introduced by AI tools, which often lack context or semantic naming.
Automated linters can flag number literals, but human insight is critical to understand if a value requires refactoring into a named constant.
Keep your eyes open for AI-generated black box numbers that might slip past initial checks but can cause maintenance headaches later.
Try Them! 🛠
Remember: AI Assistants make lots of mistakes
Suggested Prompt: Convert it to more declarative
Without Proper Instructions 📵
With Specific Instructions 👩🏫
Conclusion 🏁
You should address and remove your magic numbers to safeguard your code's readability, maintainability, and testability.
Clear, semantic naming and decoupling constants from their consumers are essential steps toward crafting cleaner, more resilient software.
Every magic number you replace with intention-revealing logic is a step away from brittle code and closer to robust, professional craftsmanship.
Don't let numbers dictate your code; define their purpose and context instead.
Relations 👩❤️💋👨
More Information 📕
Credits 🙏
Photo by Kristopher Roller on Unsplash
In a purely functional program, the value of a [constant] never changes, and yet, it changes all the time! A paradox!
Joel Spolsky
This article is part of the CodeSmell Series.
I think this sentence "Rename the constant with a semantic and name (meaningful and intention revealing)." went wrong through edition