Padrões de Codificação

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 com duas exceções principais: utiliza tabulações em vez de espaços para indentação e utiliza PascalCase para constantes de classe.

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.
• Interfaces e classes abstratas não devem conter prefixos ou sufixos 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:

	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):

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.

/**
 * 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:

/** @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.

/**
 * 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
• 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.