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

{% hint style="info" %}

* Прыклады і модулі Terraform павінны ўтрымліваць дакументацыю, якая тлумачыць іх функцыі і спосабы выкарыстання.
* Усе спасылкі ў файлах README.md павінны быць абсалютнымі, каб вэб-сайт рэестра Terraform адлюстроўваў іх правільна.
* Дакументацыя можа ўключаць дыяграмы, створаныя з дапамогай [mermaid](https://github.com/mermaid-js/mermaid) і blueprints створаныя з дапамогай [cloudcraft.co](https://cloudcraft.co).
* Выкарыстоўвайце [Terraform pre-commit hooks](https://github.com/antonbabenko/pre-commit-terraform) перад адпраўкай змен, каб пераканацца, што код з'яўляецца сапраўдным, правільна адфарматаваным і аўтаматычна дакументаваным, перш чым ён будзе адпраўлены ў git і правераны людзьмі.
  {% endhint %}

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

Каманда Terraform `terraform fmt` забяспечвае кананічны стыль для файлаў канфігурацыі. Інструмент наўмысна мае пэўныя абмежаванні і не можа быць настроены, што гарантуе адзіны фармат для ўсіх кодавых баз, каб аглядальнікі маглі засяродзіцца на сутнасці, а не на стылі. Інтэгруйце яго з [Terraform pre-commit hooks](https://github.com/antonbabenko/pre-commit-terraform) каб аўтаматычна правяраць і фарматаваць код, перш чым ён трапіць у сістэму кантролю версій.

Напрыклад:

```yaml
# .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](https://editorconfig.org/) дапамагае падтрымліваць адзіны стыль кадавання для некалькіх распрацоўшчыкаў, якія працуюць над адным праектам у розных рэдактарах і IDE. Дадавайце файл `.editorconfig` у вашы рэпазіторыі, каб падтрымліваць адзіныя прабелы і водступы.

**Прыклад `.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](https://pre-commit.com/) ёсць фрэймворкам для кіравання і падтрымкі шматмоўных pre-commit hooks. Ён напісаны на Python і з'яўляецца магутным інструментам для аўтаматычнага выканання задач на камп'ютары распрацоўшчыка перад тым, як код будзе адпраўлены ў git-рэпазіторый. Звычайна ён выкарыстоўваецца для запуску лінтэраў і фарматавання кода (гл. [supported hooks](https://pre-commit.com/hooks.html)).

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

Азнаёмцеся з [pre-commit-terraform рэпазіторыем](https://github.com/antonbabenko/pre-commit-terraform/blob/master/README.md) і існуючымі рэпазіторыямі (напрыклад, [terraform-aws-vpc](https://github.com/terraform-aws-modules/terraform-aws-vpc)) дзе гэта ўжо выкарыстоўваецца.

### terraform-docs

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

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

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

**Прыклад:**

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

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

**Прыклад:**

```hcl
# --------------------------------------------------
# AWS EC2 Instance Configuration
# --------------------------------------------------

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

@todo: Document module versions, release, GH actions

## Рэсурсы

1. [pre-commit framework homepage](https://pre-commit.com/)
2. [Collection of git hooks for Terraform to be used with pre-commit framework](https://github.com/antonbabenko/pre-commit-terraform)
3. Пост у блогу [Dean Wilson](https://github.com/deanwilson): [pre-commit hooks and terraform - a safety net for your repositories](https://www.unixdaemon.net/tools/terraform-precommit-hooks/)