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

{% 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/)


---

# Agent Instructions: Querying This Documentation

If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.

Perform an HTTP GET request on the current page URL with the `ask` query parameter:

```
GET https://www.terraform-best-practices.com/be/code-styling.md?ask=<question>
```

The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.

Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.