# Código

## Execute cada comando antes de publicar

Um bloco de código não testado é um palpite com aparência de autoridade. A prosa sinaliza incerteza com palavras; um bloco de código não sinaliza nada, e o leitor o executa com confiança total. Na página, um comando inventado é idêntico a um comando testado. A diferença aparece quando o comando falha, na máquina do leitor.

Execute cada comando e cada snippet antes de publicar a página. Quando não puder executar um, não o publique. Uma página que afirma menos, e acerta em tudo o que afirma, vale mais do que uma página que adivinha.

## Componha, não invente

Um bloco de código mistura dois tipos de conteúdo: os fatos que ele carrega e a sintaxe que os expressa. A sintaxe de ferramenta necessária para expressar um fato com fonte é composição, não invenção. Flags de `curl`, um cabeçalho `Content-Type` para um dado corpo JSON e as aspas do shell entram nessa categoria. Um novo valor de produto, campo, endpoint ou valor padrão é invenção.

Para a regra de que cada dado rastreia até uma fonte, consulte [Escolha de palavras](/pt-br/documentacao/guia-de-estilo/escrita/escolha-de-palavras/).

## Torne os placeholders óbvios e consistentes

Um placeholder tem um trabalho: o leitor precisa ver de imediato que deve substituir aquele valor. Dois formatos cumprem esse trabalho: colchetes com maiúsculas, `[TOKEN VALUE]`, e os sinais `<` e `>` com palavras minúsculas, `<your-bucket-name>`. Use um único formato para todos os placeholders de uma página; três convenções na mesma página não ensinam nenhuma.

Cada tipo de valor tem uma forma reservada:

| Tipo de valor                       | Forma                                               |
| ----------------------------------- | --------------------------------------------------- |
| Segredo ou token                    | `[TOKEN VALUE]`                                     |
| Nome ou valor fornecido pelo leitor | `<your-bucket-name>`, `<your-azion-domain>`         |
| Domínio de exemplo                  | `example.com`, `example.org`                        |
| Faixa de IP de exemplo              | `192.0.2.0/24`, `198.51.100.0/24`, `203.0.113.0/24` |

As faixas de IP são reservadas para documentação e não roteiam para nenhum destino.

- Incorreto: `--token abc123`
- Correto: `--token [TOKEN VALUE]`

`abc123` parece um valor que pode funcionar, e um leitor com pressa o cola sem alterar. `[TOKEN VALUE]` não passa por um valor real. O pior placeholder é um valor falso realista, porque esconde que existe algo para substituir.

## Introduza cada bloco de código

Uma frase antes do bloco declara o que o código faz. Um bloco de código sem contexto é um trecho que o leitor precisa decifrar antes de decidir se executa.

## Marque a linguagem, e nomeie um arquivo só quando existir um

A tag de linguagem de um fence define o destaque de sintaxe e nomeia a linguagem na barra acima de qualquer bloco de duas ou mais linhas: `bash` mostra `Shell`, `json` mostra `JSON`. Dê uma tag a todo fence, e `text` a um output sem linguagem. Um bloco de uma linha não mostra números de linha, nem barra se não tiver `title`.

Adicione `title="..."` só quando o bloco for um arquivo que o leitor salva, como `title="azion.config.js"`. O nome do arquivo toma o lugar da linguagem na barra. As props estão em [Componentes](/pt-br/documentacao/guia-de-estilo/componentes/).

## Deixe o prompt fora do que o leitor copia

Nenhum `$` ou `>` antes de um comando. O leitor cola a linha com o prompt junto, e o comando falha. Um prompt só cabe em saída mostrada em um fence, onde reproduz uma sessão real.

## Escreva comentários como prosa

Um comentário dentro de um snippet segue o idioma da página e as regras de frase, e diz por quê, não o quê. Um comentário que repete a linha abaixo dele não acrescenta nada.

## Mantenha credenciais fora dos blocos de código

Nenhuma credencial real aparece na documentação: nem uma ativa, nem uma expirada, nem uma revogada. Na página, uma credencial expirada é indistinguível de uma ativa, e por isso a proibição cobre todas por igual. Um valor inventado com formato realista é proibido pela mesma razão: nenhum leitor, e nenhum scanner, o distingue de um vazamento. Escreva o placeholder: `[TOKEN VALUE]`.

Esta seção não mostra um exemplo incorreto. Uma credencial falsa realista em um guia de estilo ainda é uma credencial falsa realista em documentação pública.