Comments in HCL in Terraform - Deep Dive

Overview - Comments in HCL

What is it?

Comments in HCL are lines or parts of lines in Terraform configuration files that are ignored by the system. They help explain what the code does or why certain choices were made. Comments do not affect how the infrastructure is created or managed. They make the code easier to read and maintain for humans.

Why it matters

Without comments, Terraform files can become confusing, especially when many people work on the same project or when you revisit code after a long time. Comments prevent mistakes by clarifying intentions and help teams collaborate smoothly. They also make troubleshooting and updating infrastructure safer and faster.

Where it fits

Before learning comments, you should understand basic Terraform syntax and how to write resources. After mastering comments, you can learn about modules, variables, and advanced Terraform features that benefit from clear documentation.

Mental Model

Core Idea

Comments are notes in your Terraform files that the computer ignores but help people understand the code.

Think of it like...

Comments are like sticky notes you put on a recipe to remind yourself why you added a pinch of salt or to warn about a tricky step.

Terraform file with comments:

  # This is a single-line comment
  resource "aws_instance" "web" {
      ami           = "ami-123456"
      instance_type = "t2.micro"  # This is an inline comment
  }

Comments start with # or // for single lines, or /* ... */ for blocks.

Build-Up - 7 Steps

1

Foundation

Single-line comments with #

Concept: How to write single-line comments using the # symbol.

In HCL, you can write a comment by starting a line with #. Everything after # on that line is ignored by Terraform. Example: # This is a comment resource "aws_s3_bucket" "bucket" { bucket = "my-bucket" } The comment explains the code but does not change it.

Result

Terraform ignores the comment line and only processes the resource block.

Knowing that # starts a comment lets you add explanations anywhere without affecting your infrastructure.

2

Foundation

Single-line comments with //

Concept: Using // as an alternative way to write single-line comments.

Besides #, you can also use // to start a single-line comment in HCL. Example: // This is also a comment resource "aws_vpc" "main" { cidr_block = "10.0.0.0/16" } Both # and // work the same way for single-line comments.

Result

Terraform ignores the line starting with // and processes the rest normally.

Understanding both # and // gives flexibility to follow different team styles or copy examples easily.

3

Intermediate

Inline comments on code lines

🤔Before reading on: Do you think comments can only be on their own lines, or can they be added after code on the same line? Commit to your answer.

Concept: How to add comments after code on the same line using # or //.

You can place comments after code on the same line by adding # or //. Example: resource "aws_instance" "web" { ami = "ami-123456" # AMI ID for the web server instance_type = "t2.micro" // Small instance type } Everything after # or // on that line is ignored.

Result

Terraform reads the resource properties but ignores the inline comments.

Inline comments let you explain specific settings right where they appear, improving clarity without extra lines.

4

Intermediate

Block comments with /* */

🤔Before reading on: Do you think block comments can span multiple lines or only one? Commit to your answer.

Concept: Using /* and */ to write comments that cover multiple lines or parts of lines.

Block comments start with /* and end with */. Everything between is ignored, even across multiple lines. Example: /* This is a block comment spanning multiple lines */ resource "aws_security_group" "sg" { name = "allow_ssh" } You can also use block comments inside lines: resource "aws_instance" "web" { ami = "ami-123456" /* AMI for web server */ } Block comments are useful for temporarily disabling code or writing longer explanations.

Result

Terraform ignores everything inside the block comment and processes the rest.

Block comments provide a flexible way to add or remove large notes without deleting code.

5

Intermediate

Comments do not affect Terraform behavior

🤔Before reading on: Do you think comments can change how Terraform creates resources? Commit to yes or no.

Concept: Comments are ignored by Terraform and do not change infrastructure or state.

No matter where you put comments, Terraform treats them as invisible. They do not affect resource creation, updates, or deletions. Example: # This comment does not create a resource resource "aws_s3_bucket" "bucket" { bucket = "my-bucket" } Removing or adding comments does not change what Terraform does.

Result

Terraform creates the same infrastructure regardless of comments.

Knowing comments are invisible to Terraform prevents confusion about why changes in comments do not trigger updates.

6

Advanced

Using comments for documentation and collaboration

🤔Before reading on: Do you think comments are only for personal notes or also important for team work? Commit to your answer.

Concept: Comments help teams understand code intent, document decisions, and ease maintenance.

In real projects, comments explain why certain values are chosen or warn about side effects. Example: resource "aws_instance" "db" { ami = "ami-789012" # Use this AMI because it has security patches instance_type = "t3.medium" // Balanced cost and performance } Good comments reduce onboarding time and prevent mistakes when others edit the code.

Result

Teams work more smoothly and avoid costly errors due to misunderstandings.

Understanding comments as communication tools improves code quality and team productivity.

7

Expert

Comments and Terraform plan/apply behavior

🤔Before reading on: If you add or remove comments, do you think Terraform plan will show changes? Commit to yes or no.

Concept: Terraform ignores comments completely during plan and apply, so comments do not cause diffs or state changes.

When you run terraform plan, Terraform compares the actual infrastructure with the configuration ignoring comments. Example: Adding a comment: # Added a note resource "aws_s3_bucket" "bucket" { bucket = "my-bucket" } Running terraform plan shows no changes. This means comments are safe to add or remove anytime without affecting deployments.

Result

Terraform plan output remains unchanged when only comments change.

Knowing comments do not affect plan or apply prevents wasted troubleshooting and reassures safe documentation.

Under the Hood

Terraform's HCL parser reads configuration files and skips any text marked as comments. It treats comments as whitespace, so they do not produce tokens or affect the syntax tree. This means comments have zero impact on the internal representation of resources or variables.

Why designed this way?

Comments were designed to be ignored to keep configuration files human-friendly without complicating parsing or execution. Supporting multiple comment styles (#, //, /* */) allows flexibility and compatibility with other languages and user preferences.

Terraform HCL file parsing flow:

┌─────────────────────┐
│  Read configuration  │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  Identify comments   │
│  (#, //, /* */)      │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  Skip comment text   │
│  Treat as whitespace │
└─────────┬───────────┘
          │
          ▼
┌─────────────────────┐
│  Parse remaining     │
│  configuration code  │
└─────────────────────┘

Myth Busters - 4 Common Misconceptions

Quick: Do you think adding comments can cause Terraform to recreate resources? Commit to yes or no.

Common Belief: Adding or changing comments can trigger Terraform to recreate or update resources.

Reality: Terraform completely ignores comments when planning or applying changes, so comments never cause resource changes.

Why it matters: Believing this can cause unnecessary fear or hesitation to document code, reducing clarity and team communication.

Quick: Can block comments /* */ be nested inside each other? Commit to yes or no.

Common Belief: You can nest block comments inside other block comments to comment out large sections safely.

Reality: HCL does not support nested block comments; starting a new /* inside an existing block comment breaks parsing.

Why it matters: Trying to nest block comments can cause syntax errors and confusion during editing.

Quick: Do you think comments can contain Terraform expressions that get evaluated? Commit to yes or no.

Common Belief: Comments can include Terraform code or expressions that Terraform will read and execute.

Reality: Comments are ignored entirely; any code inside comments is not evaluated or executed.

Why it matters: Expecting code in comments to run can lead to bugs or misunderstandings about what code is active.

Quick: Do you think all Terraform users prefer the same comment style (# vs //)? Commit to yes or no.

Common Belief: Everyone uses the same comment style, so only one style is correct or recommended.

Reality: Both # and // are valid and commonly used; style depends on team preference or copying examples.

Why it matters: Insisting on one style can cause unnecessary conflicts or reduce readability when mixing code from different sources.

Expert Zone

1

Some Terraform tools and linters can enforce comment style or require comments on certain blocks for documentation compliance.

2

Comments can be used to temporarily disable code during debugging by commenting out resource blocks or variables.

3

Terraform's JSON configuration format does not support comments, so comments only exist in HCL files, affecting tooling choices.

When NOT to use

Comments are not a substitute for proper documentation systems or version control commit messages. For complex explanations, use external documentation or README files. Avoid over-commenting trivial code that is self-explanatory.

Production Patterns

In production, teams use comments to document resource purpose, link to tickets or design docs, and warn about manual changes outside Terraform. Comments also mark deprecated resources or planned future changes.

Connections

Code Documentation

Comments are a basic form of code documentation.

Understanding comments in Terraform helps grasp the broader practice of documenting code to improve maintainability and collaboration.

Version Control Commit Messages

Comments complement commit messages by explaining code changes inline, while commits explain why changes happened.

Knowing how comments and commit messages work together improves team communication and historical tracking.

Natural Language Annotations in Scientific Papers

Both comments and annotations add human-readable explanations without affecting the main content or results.

Recognizing this parallel shows how adding explanations is a universal practice to aid understanding across fields.

Common Pitfalls

#1 Using nested block comments causing syntax errors.

Wrong approach:

/* Outer comment /* Nested comment */ Still in outer */

Correct approach:

/* Outer comment
No nested block comment inside
*/

Root cause:

Misunderstanding that HCL does not support nested block comments.

#2 Expecting comments to disable resource creation.

Wrong approach:

# resource "aws_instance" "web" { ... }

Correct approach:

/* resource "aws_instance" "web" { ... } */

Root cause:

Confusing single-line comments with block comments for disabling multi-line code.

#3 Leaving outdated or misleading comments that confuse readers.

Wrong approach:

# This resource is for staging environment
resource "aws_s3_bucket" "prod" { ... }

Correct approach:

# This resource is for production environment
resource "aws_s3_bucket" "prod" { ... }

Root cause:

Failing to update comments when code changes, leading to misinformation.

Key Takeaways

Comments in HCL are ignored by Terraform but essential for human understanding and collaboration.

You can write single-line comments with # or //, and multi-line block comments with /* */.

Comments can be placed on their own lines or inline after code to explain specific settings.

Terraform never evaluates or acts on comments, so adding or removing them does not affect infrastructure.

Proper use of comments improves team communication, reduces errors, and makes infrastructure code easier to maintain.