Terraform Comment Block: A Comprehensive Guide

Estimated reading time: 6 minutes

Last updated on November 8th, 2024 at 03:45 pm

Importance of Comments in Terraform

Terraform Comment Block is important for your infrastructure code. It improves readability and makes the code easier to understand and maintain.

By adding the comments to your Terraform code, you can improve the clarity of your infrastructure and provide the context to anyone reading.

In summary, use the Terraform Comment Block as documentation for your infrastructure to understand the purpose and functionality.

Types of Comments in Terraform

Single-Line Comments

You can use the hash symbol ( # ) for the single-line comment. It’s simple and useful for adding notes or code explanations in your configuration.

HCL
# This is a single-line comment with hash
resource "aws_instance" "example" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"
}

You can use the // symbol for the single-line comment as an alternative to the hash symbol ( # ), but remember the # comment style is the default comment style and should be used most of the time.

HCL
// This is a single-line comment with double slash
resource "aws_instance" "example" {
  ami           = "ami-0c55b159cbfafe1f0"
  instance_type = "t2.micro"
}
Example of Single-Line Comments

A single line of code is used to provide the context to the specific line of code. For example, explain the variable or the resource configurations.

For Example with the hash symbol ( # )

HCL
variable "region" {
  description = "The AWS region to deploy in"
  default     = "us-west-2" # Default region is set to us-west-2
}

For example with the double slash ( // )

HCL
variable "region" {
  description = "The AWS region to deploy in"
  default     = "us-west-2" // Default region is set to us-west-2
}

Multi-Line Comments

Comments can be single-line or multi-line. You can use Multi-line comments in Terraform with the slash-asterisk (/* */). Multi-line comments are useful for providing detailed documentation of the code block or temporarily disabling the block of code.

HCL
/*
This is a multi-line comment.
It can be multiple lines.
*/
resource "aws_s3_bucket" "example" {
  bucket = "tf-test-bucket"
}
Example of Multi-Line Comments

Multi-line comments are useful for detailed explanations or notes about the conditional and complex code structure.

HCL
/*
This resource block creates an AWS S3 bucket
with versioning enabled and a bucket policy.

Ensure that the bucket name is unique.
*/
resource "aws_s3_bucket" "example" {
  bucket = "tf-test-bucket"
  versioning {
    enabled = true
  }
}

Level Up Your DevOps Skills! 📈

Get Weekly Tips, Tutorials & Master the Latest Trends – Subscribe Now!

Subscribe Now!

Terraform Comment Block: Best Practices

Clarity and Readability

Write clear comments!

When you add the Terraform comment block, provide clarity. Why the certain code is here? what is its usage? what kind of value does it accept?

Ensure the comments are straightforward yet meaningful and add context.

HCL
# This variable defines the AWS region for deployment
variable "region" {
  description = "The AWS region to deploy in"
  default     = "us-west-2"
}

Keeping Comments Updated

Writing the Terraform comment block is not an event but an ongoing process that should be improved and updated as the project evolves.

Update your Terraform comment block to reflect the recent changes and updates. Outdated documentation can mislead the user and result in infrastructure incidents.

Documenting Complex Logic

Terraform comment block is useful for explaining conditional statements. Write a clear comment block and explain the reason behind the complex conditions.

HCL
# Conditional statement to choose the AMI based on the environment
variable "ami" {
  description = "AMI to use for the instance"
  default     = var.env == "production" ? "ami-a122d5a3" : "ami-f145aw5e4"
}

Describe Resource Dependencies

As your Terraform projects grow, the management of the Terraform module becomes complex and hard to maintain. As it grows the resource dependence increases too.

Top 5 Terraform Module Versioning Best Practices

The best practice with Terraform comment block is to write and explain what depends on each other and the relationship.

HCL
# This security group is used by the EC2 instance
resource "aws_security_group" "instance" {
  vpc_id = aws_vpc.main.id
}

Terraform Comment Block: Advanced

Using Comments for Documentation

Terraform comment block is a great way to write the in-line documentation to describe the variable, resource, and modules in detail.

HCL
# This module sets up a VPC with subnets and routing tables
module "vpc" {
  source = "terraform-aws-modules/vpc/aws"
  version = "2.77.0"
  name    = "my-vpc"
  cidr    = "10.0.0.0/16"
}

You can use tools like Terraform-docs to generate the documentation from your Terraform comment block

Automatic Comment Checks

Use the linter for the Terraform project to enforce the comment writing guideline. Linter ensures that comment consistency is maintained across the entire project.

Integrate the linter within your CI/CD pipeline to automate the lining process and documentation generation for the Terraform comment block.

Fast-Track Your DevOps Career 🚀

Stay ahead of the curve with the latest industry insights. Get weekly tips & propel your skills to the next level.

Subscribe Now!

Terraform Comment Block: Common Mistakes

Over-Commenting

Commenting can improve the code readability but as opposed to that over-commenting can cause the issue. Writing excessive comments can clutter the code base and logic.

Aim for balance between your code and comment block. Comment only when necessary not all the comments necessary.

One way to decide if the Terraform comment block is needed or not is by asking a simple question: “Does adding the comment add value and clarity?”

Ambiguous Comments

Don’t write a comment that does not provide a clear meaning. Avoid adding comments just for the sake of comment.

HCL
# Set the region
variable "region" {
  default = "us-west-2"
}

Adding comments for the above code block is not necessary and it’s self-explanatory. Be precise in your terraform code block

HCL
# Set the AWS region for deploying resources
variable "region" {
  description = "The AWS region to deploy in"
  default     = "us-west-2"
}

Conclusion

Key Takeaways:

  • Terraform comment block supports single-line and multi-line comments.
  • Write clear and meaningful comments and keep them updated.
  • Utilize tools such as Terraform-docs and linter to manage and generate documentation.
Kashyap Merai

Kashyap Merai

Kashyap Merai, a Certified Solution Architect and Public Cloud Specialist with over 7 years in IT. He helped startups in Real Estate, Media Streaming, and On-Demand industries launch successful public cloud projects.

Passionate about Space, Science, and Computers, He also mentors aspiring cloud engineers, shaping the industry's future.

Connect with him on LinkedIn to stay updated on cloud innovations.