Avoid Mental Mapping

Usage

📝 Guideline

Avoid Variable Mental Mapping: Use explicit names for variables instead of using an alias. A single-letter name is just a placeholder for the reader to map into the actual concept, and this can lead to confusion.

Mental mapping occurs when a reader or reviewer needs to decipher the meaning of a variable by inferring its purpose from its context. By using clear and descriptive names, you can eliminate mental mapping and make your code more readable and maintainable.

🛠️ How to Apply

• Use meaningful variable names that accurately describe the purpose and content of the data. 📌
• Avoid using single-letter variables unless they are widely recognized and have a clear purpose. 🚫
• Refactor code to replace ambiguous or confusing variable names with more descriptive ones. 🔁

Pros and Cons

👍 Pros

• Improved Code Comprehension: Clear and explicit variable names enhance code readability and make it easier to understand the purpose of each variable. 📚
• Reduced Mental Effort: Eliminating mental mapping reduces cognitive load and allows developers to focus on the logic and functionality of the code. 💡

👎 Cons

• Increased Code Length: Descriptive variable names can make the code longer, potentially affecting readability in some cases. 📏
• Naming Challenges: Finding the right balance between concise and descriptive variable names can be challenging, requiring careful consideration. 🔍

Examples

❌ Bad

// Bad
const x = 5 // What does 'x' represent?
const y = 10 // And what about 'y'?
const result = x * y // No context, mental mapping required

✅ Good

// Good
const width = 5 // Descriptive name for the width of a shape
const height = 10 // Descriptive name for the height of a shape
const area = width * height // Clear context, no mental mapping needed

References

🔀 Related principles

• Avoid Abbreviations: Abbreviating variable names can increase mental mapping. 🚫
• Use Descriptive Naming: Clear and meaningful names provide better understanding. 📚
• Avoid Magic Numbers: Replace unclear numeric values with named constants. 🔢