How to Comment in Terraform | Explained

Terraform, the Infrastructure as Code (IaC) tool by HashiCorp, empowers developers to manage infrastructure efficiently. One of the often overlooked yet crucial aspects of writing maintainable Terraform code is commenting. Comments can provide clarity and context to your infrastructure code. 

This article goes about the basic rules of commenting in Terraform to help ensure your code remains readable and collaborative. If you’re familiar with commenting in other coding languages, it should be a breeze. If not, there’s nothing to worry about either. You’ll see.

Why Comment in Terraform?

Commenting in Terraform can prove useful depending on what you’re working with. Regardless, here’s a few reasons why incorporating comments might be a good idea.

Documentation: Comments serve as documentation for your Terraform code. They provide insights into the purpose, functionality, and usage of various blocks, variables, and resources. Proper documentation is essential for onboarding new team members, sharing knowledge, and ensuring that others can understand your code.

Debugging and Troubleshooting: Comments can be valuable when debugging or troubleshooting issues. A well-commented codebase can help you and your team quickly identify the purpose and logic behind different components, making it easier to pinpoint and resolve problems.

Collaboration: In a collaborative environment, where multiple team members work on the same codebase, comments play a crucial role in communication. They help convey intent, rationale, and any important considerations to others who might be working on or reviewing the code.

How Do You Comment Lines in Terraform?

It’s important to note that Terraform ignores comments during the execution of the code. Comments are purely for human readability and documentation purposes. Here’s how commenting in Terraform works.

Single-Line Comments

Let’s kick off with the basics – single-line comments. Single-line comments are perfect for adding quick notes or explanations on a specific line of code. In Terraform, you can add a comment using the ‘#’ symbol or ‘//’. Anything following these symbols on a line is treated as a comment.

# This is a single-line comment
resource "aws_instance" "example" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"
}
// This is another single-line comment
variable "region" {
  type        = string
  description = "The AWS region where resources will be created"
  default     = "us-west-2"
}

Both ‘#’ and ‘//’ can be used for single-line comments. However, the default style for single-line comments is marked by the ‘#’ symbol and is recommended for most situations. Often, automatic configuration formatting tools will convert ‘//’ comments to ‘#’ comments, as the double-slash style is not considered idiomatic.

Multi-Line Comments

For more extensive comments, you can use multi-line comments enclosed in ‘/*’ and ‘*/’.

/*

  This is a multi-line comment

  providing detailed information

  about the purpose of the block.

*/

resource "aws_instance" "example" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"
}

Multi-line comments are handy when you need to provide comprehensive explanations or documentation for a block of code.

How Do You Comment Out Code Lines?

Sometimes, you may want to temporarily disable a block of code. In such cases, you can comment out the entire block using ‘/*’ and ‘*/’.

/*
resource "aws_instance" "example" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"
}
*/

This prevents Terraform from processing the commented-out code, allowing you to test or troubleshoot without executing specific resources.

Best Practices for Commenting in Terraform

Although comments are for better clarity, they can be annoying if not properly utilized. Below is a general guideline that you may follow when commenting in Terraform.

1. Be Descriptive: Provide clear and concise descriptions for variables, resources, and blocks. Explain the purpose and expected behavior of each element to make it easier for others (and yourself) to understand the code.

2. Use Inline Comments Sparingly: While comments are useful, avoid overusing inline comments for self-evident code. The goal is to enhance understanding, not clutter the code.

3. Use Consistent Formatting: Maintain a consistent commenting style throughout your codebase. Whether you prefer single-line or multi-line comments, sticking to a uniform style improves the overall readability of your Terraform configuration.

4. Consider Documentation Tools: Explore tools like Terraform-docs, which can automatically generate documentation based on comments in your Terraform code. This can streamline the documentation process and ensure consistency. 

Frequently Asked Questions

Can I use comments within resource blocks?

Comments within resource blocks are not allowed. However, you can add comments above or below the block to provide context.

Are comments preserved in Terraform state files?

Terraform state files do not store comments. They are purely for internal tracking of resource dependencies.

Conclusion

Comments provide insights into the logic, purpose, and dependencies within your infrastructure. We hope this guide has shed light on the nuances of commenting in Terraform. Do you have any questions or topics you’d like us to cover in our next guide? Let us know in the comments. Happy coding!