Unit
- Intention-revealing names: A variable name should clearly indicate what it represents and why it exists. For example,
int dis meaningless, whereasint elapsedTimeInDaysconveys both the quantity and the unit. When names reveal intent, the code becomes self-documenting and reduces the need for separate comments. - Avoid disinformation: Do not use names that imply a different meaning than intended. For instance, using
accountListfor a variable that is not aListtype misleads the reader. UseaccountsoraccountGroupinstead. Consistency with standard naming conventions prevents confusion. - Make meaningful distinctions: Avoid names like
a1,a2, ordata,infothat do not differentiate. Instead, use descriptive names such assourceanddestination, orcustomerDataandorderData. Each name should have a distinct and clear purpose. - Use pronounceable names: Names like
genymdhms(generation date, year, month, day, hour, minute, second) are hard to pronounce and remember. WritegenerationTimestampor similar. Pronounceable names facilitate verbal discussion and code reviews. - Use searchable names: Single-letter names and numeric constants are hard to search for in a codebase. Replace
7with a constant likeWORK_DAYS_PER_WEEK. Tools likegrepor IDE search work better with longer, meaningful names. - Avoid encodings: Hungarian notation type encodings (like
strNameoriCount) are unnecessary in modern statically typed languages. Type information is already provided by the compiler or interpreter. Use plain words:nameandcount. - Class and function names: Classes should have noun or noun phrase names (e.g.,
Customer,AccountParser). Methods should have verb or verb phrase names (e.g.,save(),getAddress()). Accessors, mutators, and predicates should be named for their value, with prefixes likeget,set, andis. - Be consistent across the codebase: Use the same vocabulary for similar concepts throughout your project. For example, if you use
fetchfor retrieving a resource in one module, do not switch toretrievein another. Consistency reduces cognitive load for developers. - Avoid clever or punny names: Do not use informal terms or inside jokes as names. Code is read many times by different people; what seems clever today becomes confusing tomorrow. Stick to clear, standard terminology.
- One word per concept: Do not use synonyms interchangeably. Pick one term for a given concept (e.g., always
controllerinstead ofmanagerordriver). This ensures that when developers see the word, they immediately know the role. - Use problem domain names: When naming is difficult, draw terms from the business domain or problem space. For example, use
OrderLineIteminstead of a genericItemContainer. Domain names help developers new to the project map code to real-world concepts and reduce the learning curve. - Add meaningful context: Place names in a context that clarifies their meaning. Instead of isolated variables like
state, useaddressStateor group related names inside a class. Context can come from enclosing classes, functions, or prefixes that disambiguate without being excessive. - Avoid mental mapping: Do not force readers to translate names into other meanings in their head. For instance, using a single letter
rfor a URL object because it is the first letter of the word hides the intent. WriterequestUrlso the reader does not have to remember your mapping.
Quick Revision
- Review the key concepts covered in The Power of Intention-Revealing Names.
- Apply these principles in practical working contexts.
- Connect this material to the wider module objectives.