Intention-Revealing Names
What you'll learn: How to choose names that make your code self-documenting by clearly expressing purpose and meaning.
The Core Idea
An intention-revealing name tells you why something exists, what it does, and how it's used—all without needing additional comments. When you read a variable, function, or class name, you should immediately understand its role in the code.
Think of names like labels in a well-organized filing cabinet. A folder labeled "Q3_2023" requires you to guess what's inside. But "Q3_2023_Sales_Reports" tells you exactly what you'll find. Good code names work the same way.
Why This Matters
Poor names force readers (including future you) to hunt through code to understand what's happening. They create mental overhead and slow down comprehension. When you write int d; for "days elapsed," every reader must decode what d means. But int daysSinceCreation; speaks for itself.
Names are the primary way we communicate intent in code. Since we read code far more often than we write it, investing time in clear names pays massive dividends in maintainability.
Signs of Good Intention-Revealing Names
- Self-explanatory:
calculateTotalPrice()instead ofcalc() - Specific:
activeCustomerCountinstead ofcount - Context-appropriate:
isEligibleForDiscountinstead offlag - Removes need for comments: The name itself explains the purpose
The Test
If you need a comment to explain what a name means, the name isn't revealing enough. Let the name do the explaining.
Key Takeaway: Choose names that answer "what," "why," and "how" so clearly that comments become unnecessary—make your code read like well-written prose.