In the recent Agile conference, I heard that the code should be written primarily for human readability. Good code is something that does not need any explanation or comments. It does not need any “Knowledge Transfer” from other developer. Good code must be like a book. Anyone who knows the language should be able to read and understand what the author is trying to say.
I am fascinated by the concept, but was wondering how to apply this concept while actually coding. After all, the code we write has to adhere to the syntax imposed by the language. After thinking for a while, I think I found one way to make this happen. Let me experiment this technique on you, my reader.
Let us consider an example of method used in some financial application for buying stocks. This method takes in the stock Symbol, the number of shares and customerId as parameters. Can you guess the logic of the code below?
public void BuyStock(string tickerSymbol, int numberToBuy, long customerId)
{
CompanyToTrade company = Get_CompanyToTrade_If_Valid_Ticker(tickerSymbol);
Customer validCustomer = Get_Customer_If_Valid_Id(customerId);
float totalAmount = Calculate_Transaction_Amount(company, numberToBuy);
Check_Customer_Account_Balance(validCustomer, totalAmount);
Deduct_Amount_From_Customer_Account(validCustomer, totalAmount);
bool success = StockExchange_Buy_Stock(tickerSymbol,numberToBuy,customerId);
if(success)
{
Add_Stock_To_Customer_Account(tickerSymbol,numberToBuy);
}
else
{
Rollback_Deduct_Account(validCustomer,totalAmount);
}
}
The logic I tried to implement is as follows -
- Need to see if the tickerSymbol is valid
- Need to see if the customerId is valid
- Need to see if the customer has enough money to buy the “numberToBuy” number of shares
- Deduct Money
- Buy the Stock by calling the stock exchange API
- If above call succeeded, Add stock to customer Account
- Else rollback the money deducted from the customer
Were you able to understand the logic from the code? If not, which part of the code was not clear? Please let me know in the comments section so that I can update the code.
I feel we can make use of the name of the functions to reveal the logic as it can be written in english. Hence, a good way to write readable code is break down the logic required into a set of steps in english and then convert each of these steps into function names. The actual logic of the step would be inside these functions. This has an additional advantage of following Single Responsibility Principle. Let me give an example of Calculate_Transaction_Amount function.
Initial requirement-
float Calculate_Transaction_Amount( company, numberToBuy)
{
return company.Price * numberToBuy;
}
Later on, there might be requirement to add transaction tax and brokerage charges to it. In this case, only this method needs to change. Even here, we can further sub-divide the logic into individual functions -
float Calculate_Transaction_Amount( company, numberToBuy)
{
float basePrice = company.Price * numberToBuy;
float transactionTax = Calculate_Transaction_Tax(basePrice);
float brokerageFees – Calculate_brokerage(basePrice);
return basePrice + transactionTax + brokerageFees;
}
What do you think? Do you have nay other tricks to make the code more readable?
