Why Naming Matters
- Readability: Code is read more often than it is written. Meaningful names save time for anyone reading the code later.
- Maintainability: Poorly named parameters force future developers to dig deeper into implementation details to understand what’s going on.
- Collaboration: In team environments, code is shared across developers. Descriptive names prevent unnecessary confusion and questions.
The Problem with Shorthand Naming
Consider this example:
fun createMerchant(own1Addr: String, merchAddr: String) { ... }
At a glance:
- What is own1Addr? Does it mean first owner address?
one owner address? Something else? - What is merchAddr? Probably merchant address, but why abbreviate?
Now compare it with:
fun createMerchant(firstOwnerAddress: String, merchantAddress: String) { ... }
Suddenly the method signature becomes self-explanatory. There’s no ambiguity. Even without comments, a developer immediately understands what each parameter represents.
Guidelines for Naming Parameters and Properties
1. Prefer Clarity Over Brevity
Avoid cryptic abbreviations like custNm, merchAddr, prodCd. Instead, write:
- customerName
- merchantAddress
- productCode
Typing a few extra characters is a small cost compared to the confusion shorthand creates.
2. Use Consistent Vocabulary
If you use Address in one place, don’t call it Addr or Location somewhere else. Pick one term and stick with it across the codebase.
- Good: billingAddress, shippingAddress, merchantAddress
- Bad: billAddr, shipLocation, merchAddr
Consistency builds predictability.
3. Reflect Domain Terminology
Names should match the domain you’re working in. If your business domain talks about “Merchant” and “Owner,” use those words in your code. Avoid personal shorthand.
For example:
- merchantAccountId
- merchAcc
This makes it easier for non-developers (e.g., product managers, domain experts) to follow conversations around code.
4. Avoid Redundancy
Don’t repeat information unnecessarily. If a class is Merchant, its properties don’t need to prefix with merchant.
Example:
class Merchant {
val name: String
val address: String
}
Instead of:
class Merchant {
val merchantName: String
val merchantAddress: String
}
The class context already tells you the properties belong to a merchant.
5. Name Parameters for Intention
Parameters in methods should reveal their purpose. For example:
fun schedulePayment(amount: Double, dueDate: LocalDate)
is better than:
fun schedulePayment(amt: Double, dt: LocalDate)
The former communicates what the values represent, not just their data types.
Conclusion
The next time you’re tempted to type own1Addr or merchAddr, pause and write the full, clear name. Future you—and your team—will thank you.
