Code styling

• Examples and Terraform modules should contain documentation explaining features and how to use them.

• All links in README.md files should be absolute to make Terraform Registry website show them correctly.

• Documentation may include diagrams created with mermaid and blueprints created with cloudcraft.co.

• Use Terraform pre-commit hooks to make sure that the code is valid, properly formatted, and automatically documented before it is pushed to git and reviewed by humans.

Editor Configuration

• Use .editorconfig: EditorConfig helps maintain consistent coding styles for multiple developers working on the same project across various editors and IDEs. Include an .editorconfig file in your repositories to maintain consistent whitespace and indentation.

Example .editorconfig:

[*]
indent_style = space
indent_size = 2
trim_trailing_whitespace = true

[*.{tf,tfvars}]
indent_style = space
indent_size = 2

[Makefile]
indent_style = tab

Documentation

Automatically generated documentation

pre-commit is a framework for managing and maintaining multi-language pre-commit hooks. It is written in Python and is a powerful tool to do something automatically on a developer's machine before code is committed to a git repository. Normally, it is used to run linters and format code (see supported hooks).

With Terraform configurations pre-commit can be used to format and validate code, as well as to update documentation.

Check out the pre-commit-terraform repository to familiarize yourself with it, and existing repositories (eg, terraform-aws-vpc) where this is used already.

terraform-docs

terraform-docs is a tool that does the generation of documentation from Terraform modules in various output formats. You can run it manually (without pre-commit hooks), or use pre-commit-terraform hooks to get the documentation updated automatically.

Comment style

Use # for comments. Avoid // or block comments.

Example:

# This is a comment explaining the resource
resource "aws_instance" "this" {
# ...
}

Section Headers: Delimit section headers in code with # ----- or ###### for clarity.

Example:

# --------------------------------------------------
# AWS EC2 Instance Configuration
# --------------------------------------------------

resource "aws_instance" "this" {
# ...
}

@todo: Document module versions, release, GH actions

Resources

1. pre-commit framework homepage
2. Collection of git hooks for Terraform to be used with pre-commit framework
3. Blog post by Dean Wilson: pre-commit hooks and terraform - a safety net for your repositories