The Art of Naming: Unraveling the Importance of Naming Conventions in Code.
Introduction:
In the intricate world of coding, where lines of text transform into functional software, the significance of naming conventions cannot be overstated. A well-thought-out system of naming variables, functions, and other elements within a codebase is akin to a roadmap, guiding developers through the complex landscape of their creation. Let’s delve into the realm of naming conventions and explore their pivotal role in the daily lives of engineers.
Clarity and Readability:
One of the primary reasons for adopting a consistent naming convention is to enhance code clarity and readability. Imagine a library without labeled sections or a book without chapter titles — navigating through such content would be a daunting task. Similarly, in a codebase, clear and meaningful names serve as signposts, making it easier for developers to understand the purpose and functionality of each component. It can be challenging at first, but once you establish the format of the naming convention, your entire coding process becomes easier. Other members of your team can easily understand what you’ve done and can easily contribute to it.
Maintainability and Collaboration:
Coding projects often involve collaboration among multiple developers. Consistent naming conventions facilitate seamless collaboration by creating a shared natural language. When every contributor adheres to the same standards, the code becomes more maintainable, reducing the learning curve for new team members and minimizing the chances of errors caused by misinterpretation. It is important to note that naming conventions should be a standard and not an option. It should be a culture that flows within every team in an organization. When you make the lives of others easy, you improve your own life by a significant percentage.
Debugging and Troubleshooting:
When issues arise in a codebase, the ability to quickly identify and rectify the problem is paramount. Clear and descriptive names streamline the debugging process, allowing developers to pinpoint the source of an error swiftly. I cannot emphasize enough how important this is. I have been in situations where naming conventions have saved me a lot of time while debugging. An intelligible naming convention transforms debugging from a tedious hunt into a focused investigation, saving valuable time and resources.
Consistency Across Projects:
The best thing about naming conventions is the consistency they bring to a project’s codebase. In an environment where templating is highly adopted, the true magic is unleashed when coupled with effective naming conventions. Automated processes from scripts can work with templates to benefit from consistent and meaningful names, enhancing their ability to parse, analyze, or manipulate template elements without ambiguity.
Delving into DevOps and Cloud Engineering, I have had several experiences using structured naming conventions in several codebases. In the next paragraph, I explain how we adopted naming conventions as a department in my organization and the unlimited benefits it provided us.
During the past two and half years, I have worked heavily with Ansible and Terraform to automate the setup, configuration, and deployments of critical infrastructure under the mentorship of Joseph Djomeda and Yoofi Asamoah. We lived by a basic but powerful principle; “To make our codebase a template for future projects, fostering code reuse and easing the onboarding process for new team members”. Joseph would always emphasize the need for clear and concise naming conventions. It was hard to understand why he was so passionate about it at first. Over time, I came to realize how easy it made our lives. We had a naming convention for almost everything. From naming variables & objects, through naming configurations, to naming files and folders.
It made Templating and code reuse easier because we had established an art form, a structure, and a culture that future engineers will come to love and appreciate.
Let’s delve into how you can also start creating descriptive and intelligible naming conventions.
DEFINING THE STRUCTURE OF A NAMING CONVENTION
Where to begin?
Creating a naming convention is a straightforward process and can be done in a few minutes. First, we need to identify the variables (both global and local) of the project we’re working on. For demonstration purposes, I am going to provide an example, using Terraform, an Infrastructure As Code tool that lets you build, change, and version cloud and on-prem resources safely and efficiently. The principle is the same and can be applied to any other programming language or codebase.
Scenario: Creating a VPC [Virtual Private Cloud] resource in AWS.
So what is a VPC????
A VPC is a fundamental component in cloud computing infrastructure, provided by Amazon Web Services (AWS). A VPC allows users to create a logically isolated section of the cloud where they can launch and configure compute resources, such as virtual machines, and define their network environment.
Identifying the Global and Local Variables:
Here are some examples:
Global Variables:
- country: The country for which the application is being deployed if you have a multinational setup.
- product: The name of the product or application you are creating the resources for.
- environment: The environment from which the service will be running. This could be prod, UAT, Test, DR, or even QA.
Local Variables:
- resource_type: The type of resource you are creating.
- any_other_info: Additional useful information to identify the exact resource being created.
The Structure:
For our use case, we will use the identified variables to generate the structure we want. A simple way is to concatenate the variables to form a single string value. See below;
Here is one way to represent the information we have in a format we can use.
country ==> product ==> environment ==> resource_type ==> any_other_info
Now, let’s provide some actual data to simulate what the finished format would look like.
We will use this information to fill in the variables.
- country = gh
- product = jenkinsci
- environment = prod
- resource_type = vpc
- any_other_info [optional] = [we will leave this empty for this demo but you can add any additional information here]
After filling in the details, here is an example of what my VPC resource name would be;
VPC: gh_jenkinsci_prod_vpc
It is important to know that you’ve been provided enough characters to make the name as descriptive as possible. Take advantage of that and give descriptive names. This would make it easier for others to easily identify the specific details of the object or resource you are naming. Here’s a pro tip. If you follow a good naming convention structure, you may not even need to comment on your code. You know why???? because your code is almost self-descriptive.
Demonstration:
Let's represent this in code, shall we? I am using the concept of custom modules in Terraform to achieve our goal. You can use any approach that suits your style. Eg: You can use the concept of workspaces in Terraform to dynamically determine the value of the environment.
Requirements: [Find some assistance here.]
- Terraform
- AWS CLI
- IAM user with credentials
Here is my folder structure:
~/Documents/BattleField/iac/articles/article_naming_convention main ❯ tree .
.
├── main.tf
├── modules
│ └── networking
│ ├── variables.tf
│ └── vpc.tf
├── prod.tfvars
├── providers.tf
└── variables.tf
3 directories, 6 filesHere are the steps to follow:
- Create Folder Structure and files respectively.
- Copy and paste the following code into your providers.tf file:
# Setting Required Providers
terraform {
required_providers {
aws = {
source = "hashicorp/aws"
version = "~> 5.0"
}
}
}
# Configuring the AWS Provider
provider "aws" {
region = "eu-west-1" # replace region with your prefered region code
profile = "myprofile" # replace the profile name with the configured profile you to for your awscli.
default_tags {
tags = {
Environment = var.global_var_tags_environment
Project = var.global_var_tags_product
}
}
}- Open the vpc.tf file under modules/networking and paste the following:
resource "aws_vpc" "self" {
cidr_block = "${var.vpc_var_cidr_block_prefix}.0.0/16"
tags = {
Name = "${var.global_var_tags_country}_${var.global_var_tags_product}_${var.global_var_tags_environment}_${var.vpc_var_resource_type}"
}
}- Now copy and paste the following code snippet into the variables.tf file at modules/networking
variable "vpc_var_cidr_block_prefix" {
type = string
description = "Local varieble to set CIDR block Prefix for VPC"
}
variable "global_var_tags_environment" {
type = string
description = "Global variable for setting environment type"
}
variable "global_var_tags_country" {
type = string
description = "Global variable for setting country code "
}
variable "global_var_tags_product" {
type = string
description = "Global variable for setting project name"
}
variable "vpc_var_resource_type" {
type = string
description = "Local variable for setting VPC resource type"
}- Let’s do the same for the main.tf file in the root directory. Copy and paste the code below into the file.
module "networking" {
source = "./modules/networking"
vpc_var_cidr_block_prefix = var.networking_var_vpc_cidr_block
vpc_var_resource_type = var.networking_var_vpc_resource_type
global_var_tags_environment = var.global_var_tags_environment
global_var_tags_country = var.global_var_tags_country
global_var_tags_product = var.global_var_tags_product
}- Next, copy the code below and paste it into the variables.tf file in the root directory.
variable "global_var_tags_environment" {
type = string
description = "Global variable for setting environment type"
}
variable "global_var_tags_product" {
type = string
description = "Global variable for setting project or product name"
}
variable "global_var_tags_country" {
type = string
description = "Global variable for setting country code "
}
variable "networking_var_vpc_cidr_block" {
type = string
description = "CIDR block for VPC"
}
variable "networking_var_vpc_resource_type" {
type = string
description = "Resource type for name tag"
}- Finally, copy and paste the following code into the prod.tfvars file in the root directory.
global_var_tags_environment = "prod"
global_var_tags_product = "jenkins"
global_var_tags_country = "gh"
networking_var_vpc_cidr_block = "172.28"
networking_var_vpc_resource_type = "vpc"Great Job so far, let's test this out.
Launch a terminal window in the current directory:
- Command + space on Mac, type terminal then hit the enter key.
- Ctrl + Alt + T on Windows and most Linux platforms
Run the following commands to initialize Terraform and generate a resource deployment plan.
terraform init
terraform plan -var-file=prod.tfvarsFrom the generated plan, you should see the names we defined in the tags section like this.
Now, deploy the configuration by running the following command in your terminal.
terraform apply -var-file=prod.tfvarsEnter “Yes” to approve and apply the configuration.
Once the resource is done creating, head over to your console. Navigate to VPC, and check it out. You should see something like this.
Beautiful, isn’t it? From this, it is clear how using a meaningful and descriptive naming convention can make both your life and the lives of other engineers easy. Other engineers can see this and easily understand the kind of resource it is and its purpose without needing any formal documentation or consultation.
PS: I have added more resources to the codebase to aid your practice. You’ll find everything in the repository on GitHub.
Conclusion:
To conclude this piece, a standardized approach to naming conventions ensures consistency across different codebases. This not only makes it easier for developers to transition between projects but also promotes a sense of order, clarity, and professionalism in the coding community at large. As engineers, our code is our legacy, and the art of naming is a powerful tool in shaping that legacy for the better.
