Nine practical tips to improve code quality
Being a coder, the code quality is an essential part to keep the development process happy and productive. I think it is a good thing to share my experience on how to develop better code.
It is not the `MUST FOLLOW` guide, you can also modify your own version or develop your own in order to fit your needs.
1. Keep a vocabulary list:
We use different nouns to talk about the similar things. For example, in order to say: `Stock symbol`, we also use `Ticker symbol` or `Instrument Code`, `Stock code`, etc. With different culture and experience background, people may use different words to descript the same thing, in order to avoid the misunderstanding, keep a small list for reference, and stay constant.
let tickerSymbol;
let stockSymbol;
let insturmentSymbol;
let stockCode;⬇️
let tickerSymbol;
// tickerSymbol refer as: stockSymbol, insturmentSymbol, stockCode2. Name your function with a verb prefix:
Naming a function is common, people use their imaginations to name it: `getUserList`, `userList`, `userListFromDatabase`, `usersListFromCache`.
A common English grammar rule: `Subject + Verb + Object` did the tricks if every class or object is a subject, then a verb MUST be followed, so, just name the function with a verb is a natural thing.
function getUserList() {
}function userList() {
}function userListFromDatabase() {
}function userListFromCache() {
}
⬇️
function getUserListFromDatabase() {
}function getUserListFromCache() {
}
3. Use a prefix for parameters and return values:
When the function got lots of variables, you may find it difficult to read and understand. Using a prefix can let you read the most important variables inside a function. My personal favorite is using an `a` for arguments, and `r` for the return values, some people may use `i` for inputs, and `o` for outputs. Both ways work fine and work great.
function doMyMagic(magicElement1, magicElement2) {
return magicElement1 + magicElement2;
}⬇️
function doMyMagic(aMagicElement1, aMagicElement2) {
let rMagicResult = aMagicElement1 + aMagicElement2
return rMagicResult;
}4. All numbers should assign to variables:
One of the most headaches in the source code is uncommented number. Instead of using a comment to comment the numbers, why don’t just assign it to a variable? Just more easy to read and meaningful.
function getMinimiumSupportVersion() {
return 7.0;
}⬇️
const kMinSupportVersion = 7.0;
function getMinimiumSupportVersion() {
let rMinSupportVersion = kMinSupportVersion;
return rMinSupportVersion;
}5. Develop an abbreviation list:
In order to type less, we usually use an abbreviation for long words. But not all people have common understandings of the abbreviation practice, for instance, some people use `ad` to represent `Advertisement`; some may use `adv`. Just keep a list to make everyone speak in the same language.
6. Naming a variable from top to bottom:
Let’s say you are building a registration form, you have lots of labels. The common naming may look like this:
let firstNameLabel;
let lastNameLabel;
let ageLabel;
let addressLine1Label;
let addressLine2Label;
let addressLine3Label;but in real life, when you what to interactive with the variable, you may not instantly recall the label name, but you can recall it is a label. For example, you are not sure whether you named `lastNameLabel` or `familyNameLabel`.
Naming the variable from the most common element first like follow:
let labelNameFirst;
let labelNameLast;
let labelAge;
let labelAddressLine1;
let labelAddressLine2;
let labelAddressLine3;Your brain will think in this way:
a. It is a label.
b. This label should be related to the name.
When you start typing the `label`, the editor / IDE will filter the `label`, and it filters the `label` with `Name`, it is more logical to think and filter in the same peace.
7. Use the words as short as possible:
Sometimes, we use different words for the same meaning: `last name`, `family name`, `surname`. As we suggested before, we can build a vocabulary list to stay constant, if there are no references or preferences, pick the shortest word. In this example, we will choose the `surname`.
8. Use positive vocabularies to name the variables:
Can you guess the meaning of this code `!isNotDisconnected`? It is NOT a fun task to play a brain twister especially when you are debugging the critical issue. Just make it simple: `!isConnected`.
9. Use special words to comment the code:
Comments are useful, especially useful and searchable comment. In order to make it more easy to search, the following special words can be used before comments, also you always can develop your own list for your team:
//NOTE
//OPTIMIZE
//TODO
//HACK
//XXX
//FIXME
//BUGFinally, in order to show all the things together, we have a simple example for you so that you can see how’s everything works together:
function userListFromDatabase(userName, password) {
let allUserList = [];if (!DatabaseUtil.isDisconnected) {
allUserList = DatabaseUtil.queryUserList(userName, password);
}return allUserList;
}// Please remember to handle the database is not connected.
userTable.display(userListFromDatabase(‘userName’, ‘password’));
⬇️
function getUserListFromDB(aUserName, aPassword) {
let rAllUserList = [];if (DBUtil.connected) {
rAllUserList = DBUtil.getUserList(aUserName, aPassword);
}return rAllUserList;
}// TODO: Handle the database is not connected.
tableUser.display(getUserListFromDB(‘userName’, ‘password’));
That’s it. ;) Happy Coding!

