Padrão de codificação
*********************

Este documento descreve as regras e recomendações para o desenvolvimento da Nette. Ao contribuir com o código para Nette, você deve segui-las. A maneira mais fácil de fazer isso é imitar o código existente.
A idéia é fazer com que todo o código pareça ter sido escrito por uma só pessoa. .[perex]

Nette Coding Standard corresponde ao [PSR-12 Extended Coding Style |https://www.php-fig.org/psr/psr-12/] com duas exceções principais: utiliza [abas em vez de espaços |#tabs instead of spaces] para recuo, e utiliza [PascalCase para constantes de classe |https://blog.nette.org/pt/por-menos-gritos-no-codigo].


Regras gerais .[#toc-general-rules]
===================================

- Todo arquivo PHP deve conter `declare(strict_types=1)`
- Duas linhas vazias são usadas para separar métodos para uma melhor legibilidade.
- O motivo do uso do operador de fechamento deve ser documentado: `@mkdir($dir); // @ - directory may exist`
- Se for usado um operador de comparação de digitação fraca (ou seja, `==`, `!=`, ...), a intenção deve ser documentada: `// == to accept null`
- Você pode escrever mais exceções em um arquivo `exceptions.php`
- A visibilidade dos métodos não é especificada para as interfaces, pois elas são sempre públicas.
- Cada propriedade, valor de retorno e parâmetro deve ter um tipo especificado. Por outro lado, para as constantes finais, nunca especificamos o tipo porque ele é óbvio.
- Citações simples devem ser usadas para delimitar a cadeia, exceto quando o próprio literal contém apóstrofos.


Convenções de Nomeação .[#toc-naming-conventions]
=================================================

- Evite usar abreviações, a menos que o nome completo seja excessivo.
- Use maiúsculas para abreviações de duas letras, e pascal/camelo para abreviações mais longas.
- Use um substantivo ou frase de substantivo para nome de classe.
- Os nomes de classe devem conter não somente especificidade (`Array`), mas também generalidade (`ArrayIterator`). A exceção são os atributos PHP.
- "Constantes de classe e enumeração devem usar PascalCaps":https://blog.nette.org/pt/por-menos-gritos-no-codigo.
- "Interfaces e classes abstratas não devem conter prefixos ou postfixos":https://blog.nette.org/pt/prefixos-e-sufixos-nao-pertencem-a-nomes-de-interface como `Abstract`, `Interface` ou `I`.


Embalagem e suportes .[#toc-wrapping-and-braces]
================================================

O Nette Coding Standard corresponde ao PSR-12 (ou PER Coding Style), em alguns pontos ele o especifica mais ou o modifica:

- As funções da seta são escritas sem um espaço antes do parêntese, ou seja `fn($a) => $b`
- não é necessária nenhuma linha vazia entre os diferentes tipos de declarações de importação `use`
- o tipo de retorno de uma função/método e o colchete de abertura estão sempre em linhas separadas:

```php
	public function find(
		string $dir,
		array $options,
	): array
	{
		// corpo do método
	}
```

A chave de abertura em uma linha separada é importante para separar visualmente a assinatura da função/método do corpo. Se a assinatura estiver em uma linha, a separação é clara (imagem à esquerda); se estiver em várias linhas, no PSR as assinaturas e os corpos se misturam (no meio), enquanto no padrão Nette eles permanecem separados (à direita):

[* new-line-after.webp *]


Blocos de Documentação (phpDoc) .[#toc-documentation-blocks-phpdoc]
===================================================================

A regra principal: nunca duplicar nenhuma informação de assinatura como tipo de parâmetro ou tipo de retorno sem nenhum valor agregado.

Bloco de documentação para definição de classe:

- Começa por uma descrição de classe.
- Segue a linha vazia.
- As anotações `@property` (ou `@property-read`, `@property-write`) seguem, uma por linha. A sintaxe é: anotação, espaço, tipo, espaço, $name.
- Seguem as anotações `@method`, uma a uma linha. A sintaxe é: anotação, espaço, tipo de retorno, espaço, nome(tipo $param, ...).
- A anotação `@author` é omitida. A autoria é mantida em um histórico do código fonte.
- As anotações `@internal` ou `@deprecated` podem ser usadas.

```php
/**
 * MIME message part.
 *
 * @property string $encoding
 * @property-read array $headers
 * @method string getSomething(string $name)
 * @method static bool isEnabled()
 */
```

O bloco de documentação para bens que contém apenas a anotação `@var` deve estar em uma única linha:

```php
/** @var string[] */
private array $name;
```

Bloco de documentação para definição do método:

- Começa por uma breve descrição do método.
- Nenhuma linha vazia.
- As anotações `@param`, uma por linha.
- A anotação `@return`.
- As anotações `@throws`, uma a uma linha.
- As anotações `@internal` ou `@deprecated` podem ser usadas.

Toda anotação é seguida por um espaço, exceto a `@param` que é seguida por dois espaços para uma melhor legibilidade.

```php
/**
 * Finds a file in directory.
 * @param  string[]  $options
 * @return string[]
 * @throws DirectoryNotFoundException
 */
public function find(string $dir, array $options): array
```


Separadores em vez de Espaços .[#toc-tabs-instead-of-spaces]
============================================================

As abas têm várias vantagens sobre os espaços:

- O tamanho do travessão é personalizável em editores e "web":https://developer.mozilla.org/en-US/docs/Web/CSS/tab-size.
- eles não impõem a preferência do tamanho do recuo do usuário ao código, portanto o código é mais portátil
- você pode digitá-las com um toque de tecla (em qualquer lugar, não apenas nos editores que transformam as abas em espaços)
- A indentação é seu propósito
- respeitar as necessidades dos colegas deficientes visuais e cegos

Ao utilizar abas em nossos projetos, permitimos a personalização da largura, que pode parecer desnecessária para a maioria das pessoas, mas é essencial para as pessoas com deficiências visuais.

Para programadores cegos que usam displays braille, cada espaço é representado por uma célula braille e ocupa um espaço valioso. Portanto, se o recuo padrão for de 4 espaços, um recuo de 3º nível desperdiça 12 células braile antes do início do código.
Em um display de 40 células, que é o mais comumente usado em laptops, isso é mais de um quarto das células disponíveis desperdiçadas sem nenhuma informação.


{{priority: -1}}