Coding Best Practices - Part 1

Naming Variables

Naming conventions for variables might be one of the most debated topics in the programming world. This short article will attempt to pass on learnings from professional experience I've had the priviledge of having.

When I name variables I look for 3 specific things.

  • Simple - the less words you can use to specify the variables intent, the better... however, simplicity should not cloud the intention of the variable. See SEO Horror Story below.
  • Clear intention - The intention of the variable should be implied by it's name. It should be immediately clear to a new engineer what the variable is why it is used. The more the who, what, when, where, why and how are answered from the naming convention, the better.
  • Easy to find - The variable should be unique enough that you should be able to easily hunt it down in the search of your favorite IDE.

Here's an Golang example to quickly demonstrate this point.

Code that's difficult to read...


package main

import (
"fmt"
)

func main() {
a := []int{}
r := [4]int{10, 42, 87, 26}
for _, v := range r {
a = append(a, v)
}
fmt.Println("Ages: ",a)
}

In this first example there are a few very obvious issues. First, the variable names a and r have no meaning to anyone outside the initial author of the code. You could infer that r is a group of ages because of the print statement at the end of the code. But where did they come from? Why do we need them? Another issue is the slice we're stuffing them in. What are we gathering the ages for? How are we using them?

Great code


package main

import (
"fmt"
)

func main() {
agesMarketingStats := []int{}
returnedCustomerAges := [4]int{10, 42, 87, 26}
for _, customerAge := range returnedCustomerAges {
agesMarketingStats = append(agesMarketingStats, customerAge)
}
fmt.Println("Ages: ", agesMarketingStats)
}

Notice the immediate difference in readability of the second example. Where the ages come from is clear... the customer database. What the ages are being used for is obvious... marketing statistics. The names are not overkill, but much more clear. Better yet, we don't have to worry about the length of the variable names in this case because Golang is a compiled language.

SEO Horror Story

I've done technical SEO optimization for several companies in my career. And all the front-end code was written in PHP. When you have a website with minimal pages, you don't need to pay particular attention to the amount of bytes used per page. But when your website has Millions of pages, the amount of bytes per page can seriously effect your crawl budget alloted by Google. Less bytes = more pages crawled = more pages indexed. Simple, right? Here is where the trap is with languages like PHP. Since it's not compiled, every letter and word adds to the size of the page, even when using compression. Now we're talking milliseconds of crawl budget... but milliseconds matter and make a difference with millions of pages.

Take the following example...


function dataFromCustomerPurchases() {
$returnedCustomersFromPurchases = ['Neo','Morpheus','Trinity'];
return $returnedCustomersFromPurchases;
}

$customersWhoPurchased = dataFromCustomerPurchases();

echo json_encode($customersWhoPurchased, JSON_PRETTY_PRINT);

To save precious bytes, we could go so far as to do something like this...


function d() {
$r = ['Neo','Morpheus','Trinity'];
return $r;
}

$cWP = d();

echo json_encode($cWP, JSON_PRETTY_PRINT);

We've accomplished our goal of reducing bytes... but what have we lost? If the author of the code leaves the company, this code would be extremely difficult for the new engineer to decipher and even hunt down, searching in an IDE. A better solution would be to split the difference in this case...


function buyerNames() {
$buyers = ['Neo','Morpheus','Trinity'];
return $buyers;
}

$clients = buyerNames();

echo json_encode($clients, JSON_PRETTY_PRINT);

This is still extremely minimal compared to our initial example, accomplishes simplicity with intent and even improves on our initial example reduces bytes while further clarifying our usage. When trying to reduce code and improve naming conventions, synonyms and refactoring are your best friends!

Conclusion

Naming variables is important. The ability to improve, iterate and fix bugs is essential in our fast paced, ever changing technological landscape. Do yourself and your teammates a favor and take the short amount of time it takes to use naming conventions well to further the quality, simplicity and readability of your code. The future of your company and career may depend on it.