Code Smell 02 - Don’t Let Mysterious Numbers Rule Your Code

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 😔

• Coupling
• Low testability
• Low readability

Solutions 😃

1. Rename the constant with a semantic and name (meaningful and intention revealing).
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 ⚙️

https://hackernoon.com/improving-the-code-one-line-at-a-time?embedable=true

https://hackernoon.com/refactoring-025-decompose-regular-expressions?embedable=true

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 🚫

<?

function energy($mass) {
    return $mass * (299792 ** 2)
}

Right 👉

# Storing magnitudes without units is another smell
class PhysicsConstants
   LIGHT_SPEED = 299792458.freeze
end

def energy(mass)
    mass * PhysicsConstants::LIGHT_SPEED ** 2
end

Detection 🔍

Many linters can detect number literals in attributes and methods.

Tags 🏷️

• Declarative Code

Level 🔋

• 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

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 👩‍❤️‍💋‍👨

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxii

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxvi

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-ii-o96s3wl4

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxiii

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xxxx

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-xli

More Information 📕

https://refactoring.guru/es/replace-magic-number-with-symbolic-constant?embedable=true

https://hackernoon.com/how-to-decouple-a-legacy-system-zf153u42?embedable=true

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

https://hackernoon.com/400-thought-provoking-software-engineering-quotes?embedable=true

This article is part of the CodeSmell Series.

https://hackernoon.com/how-to-find-the-stinky-parts-of-your-code-part-i-xqz3evd?embedable=true