Naming Things
Every software developer I have ever spoken to has been tripped up by variable, method and class names that are hard to understand or ambiguous. Almost all of them, the good ones at least, had stopped while writing code to consider how easy it will be for future developers to read - "Does this name make name sense?"
Naming should be agreed upon by the team, even if ad hoc as part of the code review process.
At the least, even if there are no official rules defined; being consistent with naming things will help you read your own code, even after you have shifted projects months later and have to come back to upgrade an outdated package.
In to the Goldilocks Zone
Not too long, not too short. Single letter identifiers are obviously not readable, and our compilers will take care of long code for production. So, don’t use them.
At the same time, naming something with a long, overly descriptive identifier can be just as unreadable. These long names can be harder to read at a glance and can be mixed up with others of similar names. getMobileCustomerIdAndPhoneIdByMobileServiceNumber and getMobileCustomerDetailsByMobileServiceNumber for example.
Although there is no max number of characters for the ideal identifier, it feels to be somewhere between 1-4 "words", short and readable.
Get consistent
getUser(){…}
fetchUser(){…}
retrieveUser(){…}
All these method names are the same and can be interpreted as such. It doesn’t matter which you pick, but it’s important that you’re consistent.
If you decide that get will request remote data; stick with it. getData(), getBalance() etc.
It's time to disambiguate
const dataBalanceForService
Overly specific identifiers are justified if there are too many that are similar. However, there is no need to have such long names when you don't need to infer between other identifiers, especially if there is already context. const dataBalance
Speaking of...
Context is everything
There is no need to repeat a class name within a class.
class orderAdapter {
addClientToOrder() {…}
}
We already know this is an "order". Make things easier to read by avoiding the context.
class orderAdapter {
addClient() {…}
}
isATrick
Boolean identifiers can be simple to understand and identify the type just by adding "is". isActive vs. active or isSuccessful vs. successful.
We can now see at a glace that these are boolean.
Don't forget to stay positive, isDisabled should become isEnabled
Nobody wants a tongue twister
Variable names that are hard to pronounce, no one will remember.
const actServ // the active service
const dbQry
Moreover, code should be searchable. Better naming makes for better scaling.
Wrapping up
In the end; choose whatever works for you and your team. The important part is consistency and readability.
Remember; humans read your code.
The views expressed on this blog post are mine alone and do not necessarily reflect the views of my employer, Optus Administration Pty Ltd
