Padrões de Codificação
**********************

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

Os Padrões de Codificação Nette correspondem ao [PSR-12 Extended Coding Style |https://www.php-fig.org/psr/psr-12/] com duas exceções principais: utiliza [#tabulações em vez de espaços] para indentação e utiliza [PascalCase para constantes de classe|https://blog.nette.org/en/less-noise-in-code].


Regras gerais
=============

- Cada arquivo PHP deve conter `declare(strict_types=1)`
- Duas linhas em branco são usadas para separar métodos para melhor legibilidade.
- O motivo para usar o operador shut-up (@) deve ser documentado: `@mkdir($dir); // @ - o diretório pode já existir`.
- Se for usado um operador de comparação de tipo fraco (ou seja, `==`, `!=`, ...), a intenção deve ser documentada: `// == aceita null`
- Você pode escrever várias exceções num único arquivo `exceptions.php`.
- A visibilidade do método não é especificada para interfaces, pois são sempre públicas.
- Cada propriedade, valor de retorno e parâmetro deve ter um tipo especificado. Por outro lado, nunca especificamos o tipo para constantes finais (`final const`), pois é óbvio.
- Aspas simples devem ser usadas para delimitar strings, exceto quando o próprio literal contém apóstrofos.


Convenções de Nomenclatura
==========================

- Não use abreviações, a menos que o nome completo seja muito longo.
- Use letras maiúsculas para abreviações de duas letras, Pascal/CamelCase para abreviações mais longas.
- Use um substantivo ou frase nominal para o nome da classe.
- Os nomes das classes devem conter não apenas a especificidade (`Array`), mas também a generalidade (`ArrayIterator`). Exceções são atributos da linguagem PHP.
- "Constantes de classe e enums devem usar PascalCaps":https://blog.nette.org/en/less-noise-in-code.
- "Interfaces e classes abstratas não devem conter prefixos ou sufixos":https://blog.nette.org/pt/prefixes-and-suffixes-do-not-belong-in-interface-names como `Abstract`, `Interface` ou `I`.


Quebra de Linha e Chaves
========================

Os Padrões de Codificação Nette correspondem ao PSR-12 (ou PER Coding Style), em alguns pontos complementam-no ou modificam-no:

- arrow functions são escritas sem espaço antes do parêntese, ou seja, `fn($a) => $b`
- não é necessária uma linha em branco entre diferentes tipos de declarações de importação `use`
- o tipo de retorno da função/método e a chave 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 `{` numa linha separada é importante para a separação visual da assinatura da função/método do corpo. Se a assinatura estiver numa única linha, a separação é clara (imagem à esquerda). Se estiver em várias linhas, no PSR as assinaturas e o corpo fundem-se (meio), enquanto no padrão Nette permanecem separados (direita):

[* new-line-after.webp *]


Blocos de Documentação (phpDoc)
===============================

Regra principal: Nunca duplique informações da assinatura, como o tipo do parâmetro ou o tipo de retorno, sem adicionar valor (por exemplo, uma descrição).

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

- Começa com a descrição da classe.
- Seguido por uma linha em branco.
- Seguem-se as anotações `@property` (ou `@property-read`, `@property-write`), uma por linha. A sintaxe é: anotação, espaço, tipo, espaço, `$nome`.
- Seguem-se as anotações `@method`, uma por linha. A sintaxe é: anotação, espaço, tipo de retorno, espaço, `nome(tipo $param, ...)`.
- A anotação `@author` é omitida. A autoria é mantida no histórico do código-fonte.
- Podem ser usadas as anotações `@internal` ou `@deprecated`.

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

Um bloco de documentação para uma propriedade, que contém apenas a anotação `@var`, deve ser de linha única:

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

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

- Começa com uma breve descrição do método.
- Sem linha em branco entre a descrição e as anotações.
- Anotações `@param`, uma por linha.
- Anotação `@return`.
- Anotações `@throws`, uma por linha.
- Podem ser usadas as anotações `@internal` ou `@deprecated`.

Cada anotação (`@return`, `@throws`, etc.) é seguida por um espaço. A exceção é `@param`, que é seguida por dois espaços para melhor legibilidade.

```php
/**
 * Encontra um arquivo no diretório.
 * @param  string[]  $options
 * @return string[]
 * @throws DirectoryNotFoundException
 */
public function find(string $dir, array $options): array
```


Tabulações em Vez de Espaços
============================

As tabulações têm várias vantagens sobre os espaços:

- o tamanho do recuo pode ser ajustado em editores e na "web":https://developer.mozilla.org/en-US/docs/Web/CSS/tab-size
- não impõem a preferência de tamanho de indentação do utilizador ao código, tornando o código mais portátil
- podem ser digitadas com um único toque de tecla (em qualquer lugar, não apenas em editores que convertem tabulações em espaços)
- a indentação é o seu propósito
- respeitam as necessidades de colegas com deficiência visual e cegos

Ao usar tabulações nos nossos projetos, permitimos o ajuste da largura, o que pode parecer supérfluo para a maioria das pessoas, mas é essencial para pessoas com deficiência visual.

Para programadores cegos que usam displays Braille, cada espaço representa uma célula Braille. Portanto, se a indentação padrão for de 4 espaços, uma indentação de 3º nível desperdiça 12 valiosas células Braille antes mesmo do início do código. Num display de 40 células, que é o mais comum em portáteis, isso representa mais de um quarto das células disponíveis sendo desperdiçadas sem qualquer informação.


{{priority: -1}}