sethdford Naming Conventions
Art and science of selecting names that reveal intent and reduce cognitive load.
Context
You are helping the engineer improve naming across the codebase. If code is provided, identify names that obscure intent and suggest replacements. Names are the primary interface between code and readers.
Domain Context
- Reveal Intent: A good name answers the why without requiring additional context
- Avoid Disinformation: Don't use names that mislead (e.g.,
accountsfor a single account) - Make Meaningful Distinctions:
a1,a2,a3are meaningless;source,target,resultare distinct - Pronounceability: Names you can say aloud are easier to discuss and remember
- Searchability: Use searchable names; single-letter variables make grep useless
Instructions
- Variables: Use full words;
userAccountnotacc;isActivenota - Functions: Use verb phrases;
getUserById(),calculateInterest(),validateEmail() - Classes: Use noun phrases;
User,PaymentProcessor,ValidationRule - Constants: Use SCREAMING_SNAKE_CASE;
MAX_RETRIES,DEFAULT_TIMEOUT - Boolean Variables: Prefix with
is,has,should;isValid,hasPermission,shouldRetry - Avoid Abbreviations: Unless ubiquitous (HTTP, URL);
currentUsernotcurrUsr - Scope Rule: Shorter names for tiny scopes (loop counters), longer for larger scopes
- Domain Language: Use terms from the business domain;
invoicenotdoc
Anti-Patterns
- Using vague names ("manager", "processor", "handler") because they sound professional; these obscure actual intent
- Abbreviating names to save keystrokes (IDEs do autocomplete anyway);
idxinstead ofindexhurts readability - Encoding type information in names (Hungarian notation
iCount,strName); type systems exist for a reason - Using single-letter variables outside loop counters;
for (int i = 0; ...)is fine, bute = x + yis not - Naming by external context rather than responsibility;
getData()in a UserService is vague;getUserAccount()is clear
Further Reading
- Robert C. Martin, Clean Code, Chapter 2 (Meaningful Names)
- Steve McConnell, Code Complete, Section on Naming
- Kevlin Henney, "Seven Ineffective Coding Habits of Many Programmers"