Стылізацыя кода

• Прыклады і модулі Terraform павінны ўтрымліваць дакументацыю, якая тлумачыць іх функцыі і спосабы выкарыстання.

• Усе спасылкі ў файлах README.md павінны быць абсалютнымі, каб вэб-сайт рэестра Terraform адлюстроўваў іх правільна.

• Дакументацыя можа ўключаць дыяграмы, створаныя з дапамогай mermaid і blueprints створаныя з дапамогай cloudcraft.co.

• Выкарыстоўвайце Terraform pre-commit hooks перад адпраўкай змен, каб пераканацца, што код з'яўляецца сапраўдным, правільна адфарматаваным і аўтаматычна дакументаваным, перш чым ён будзе адпраўлены ў git і правераны людзьмі.

Фарматаванне

Каманда Terraform terraform fmt забяспечвае кананічны стыль для файлаў канфігурацыі. Інструмент наўмысна мае пэўныя абмежаванні і не можа быць настроены, што гарантуе адзіны фармат для ўсіх кодавых баз, каб аглядальнікі маглі засяродзіцца на сутнасці, а не на стылі. Інтэгруйце яго з Terraform pre-commit hooks каб аўтаматычна правяраць і фарматаваць код, перш чым ён трапіць у сістэму кантролю версій.

Напрыклад:

# .pre-commit-config.yaml
repos:
  - repo: https://github.com/antonbabenko/pre-commit-terraform
    rev: v1.99.4
    hooks:
      - id: terraform_fmt

У CI pipelines выкарыстоўвайце terraform fmt -check для праверкі адпаведнасці. Праграма выходзіць з кодам статусу 0, калі ўсе файлы правільна адфарматаваны; у адваротным выпадку яна вяртае ненулявы код і пералічвае файлы з парушэннямі. Такая цэнтралізацыя фарматавання змяншае цяжкасці пры зліцці змен і ўводзіць адзіны стандарт для ўсіх каманд.

Editor Configuration

• Выкарыстоўвайце .editorconfig: EditorConfig дапамагае падтрымліваць адзіны стыль кадавання для некалькіх распрацоўшчыкаў, якія працуюць над адным праектам у розных рэдактарах і IDE. Дадавайце файл .editorconfig у вашы рэпазіторыі, каб падтрымліваць адзіныя прабелы і водступы.

Прыклад .editorconfig:

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

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

[Makefile]
indent_style = tab

Дакументацыя

Аўтаматычна згенераваная дакументацыя

pre-commit ёсць фрэймворкам для кіравання і падтрымкі шматмоўных pre-commit hooks. Ён напісаны на Python і з'яўляецца магутным інструментам для аўтаматычнага выканання задач на камп'ютары распрацоўшчыка перад тым, як код будзе адпраўлены ў git-рэпазіторый. Звычайна ён выкарыстоўваецца для запуску лінтэраў і фарматавання кода (гл. supported hooks).

З канфігурацыямі Terraform можна выкарыстоўваць pre-commit для фарматавання і праверкі кода, а таксама для абнаўлення дакументацыі.

Азнаёмцеся з pre-commit-terraform рэпазіторыем і існуючымі рэпазіторыямі (напрыклад, terraform-aws-vpc) дзе гэта ўжо выкарыстоўваецца.

terraform-docs

terraform-docs ёсць інструментам, які генеруе дакументацыю з модуляў Terraform у розных выхадных фарматах. Яго можна запускаць уручную (без pre-commit hooks), або выкарыстоўваць pre-commit-terraform hooks , каб дакументацыя абнаўлялася аўтаматычна.

Стыль каментароў

Выкарыстоўвайце # для каментароў. Пазбягайце // або блочных каментароў.

Прыклад:

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

Загалоўкі раздзелаў: для яснасці раздзяляйце загалоўкі раздзелаў у кодзе сімваламі # ----- або ######.

Прыклад:

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

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

@todo: Document module versions, release, GH actions

Рэсурсы

1. pre-commit framework homepage

2. Collection of git hooks for Terraform to be used with pre-commit framework

3. Пост у блогу Dean Wilson: pre-commit hooks and terraform - a safety net for your repositories