Estándar de codificación

Este documento describe las reglas y recomendaciones para el desarrollo de Nette. Al contribuir con código a Nette, debes seguirlas. La forma más sencilla de hacerlo es imitar el código existente. El objetivo es que todo el código parezca escrito por una sola persona.

El Estándar de Codificación de Nette corresponde al PSR-12 Extended Coding Style con dos excepciones principales: utiliza tabuladores en lugar de espacios para la indentación y utiliza PascalCase para las constantes de clase.

Reglas generales

Cada archivo PHP debe contener declare(strict_types=1).
Se utilizan dos líneas vacías para separar métodos para una mejor legibilidad.
La razón para usar el operador de silencio (@) debe documentarse: @mkdir($dir); // @ - el directorio puede existir.
Si se utiliza un operador de comparación de tipo débil (es decir, ==, !=, …), la intención debe documentarse: // == aceptar null.
Puedes escribir múltiples excepciones en un solo archivo exceptions.php.
La visibilidad de los métodos no se especifica para las interfaces, ya que siempre son públicas.
Cada propiedad, valor de retorno y parámetro debe tener un tipo especificado. Por el contrario, nunca especificamos el tipo para las constantes final, ya que es obvio.
Se deben usar comillas simples para delimitar cadenas, excepto en los casos en que el literal mismo contenga apóstrofes.

Convenciones de nomenclatura

No uses abreviaturas a menos que el nombre completo sea demasiado largo.
Usa mayúsculas para acrónimos de dos letras, PascalCase/camelCase para acrónimos más largos.
Usa un sustantivo o una frase nominal para el nombre de la clase.
Los nombres de las clases deben contener no solo la especificidad (Array), sino también la generalidad (ArrayIterator). La excepción son los atributos del lenguaje PHP.
Las constantes de clase y los enums deben usar PascalCaps.
Las interfaces y las clases abstractas no deben contener prefijos o sufijos como Abstract, Interface o I.

Envoltura y llaves

El Estándar de Codificación de Nette corresponde a PSR-12 (o PER Coding Style), en algunos puntos lo complementa o modifica:

Las funciones de flecha se escriben sin espacio antes del paréntesis, es decir, fn($a) => $b.
No se requiere una línea vacía entre diferentes tipos de declaraciones de importación use.
El tipo de retorno de la función/método y la llave de apertura siempre están en líneas separadas:

	public function find(
		string $dir,
		array $options,
	): array
	{
		// cuerpo del método
	}

La llave de apertura en una línea separada es importante para la separación visual de la firma de la función/método del cuerpo. Si la firma está en una línea, la separación es clara (imagen izquierda); si está en varias líneas, en PSR las firmas y el cuerpo se fusionan (medio), mientras que en el estándar de Nette siguen separados (derecha):

Bloques de documentación (phpDoc)

Regla principal: Nunca dupliques ninguna información en la firma, como el tipo de parámetro o el tipo de retorno, sin valor añadido.

Bloque de documentación para la definición de clase:

Comienza con la descripción de la clase.
Sigue una línea vacía.
Siguen las anotaciones @property (o @property-read, @property-write), una tras otra. La sintaxis es: anotación, espacio, tipo, espacio, $nombre.
Siguen las anotaciones @method, una tras otra. La sintaxis es: anotación, espacio, tipo de retorno, espacio, nombre(tipo $param, …).
La anotación @author se omite. La autoría se conserva en el historial del código fuente.
Se pueden usar las anotaciones @internal o @deprecated.

/**
 * Parte del mensaje MIME.
 *
 * @property string $encoding
 * @property-read array $headers
 * @method string getSomething(string $name)
 * @method static bool isEnabled()
 */

El bloque de documentación para una propiedad, que contiene solo la anotación @var, debe ser de una sola línea:

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

Bloque de documentación para la definición de método:

Comienza con una breve descripción del método.
Sin línea vacía.
Anotaciones @param en líneas individuales.
Anotación @return.
Anotaciones @throws, una tras otra.
Se pueden usar las anotaciones @internal o @deprecated.

Cada anotación va seguida de un espacio, excepto @param, que va seguida de dos espacios para una mejor legibilidad.

/**
 * Encuentra un archivo en el directorio.
 * @param  string[]  $options
 * @return string[]
 * @throws DirectoryNotFoundException
 */
public function find(string $dir, array $options): array

Tabuladores en lugar de espacios

Los tabuladores tienen varias ventajas sobre los espacios:

El tamaño del espaciado se puede personalizar en los editores y en la web.
No imponen al código la preferencia del usuario sobre el tamaño de la indentación, por lo que el código es más portátil.
Se pueden escribir con una sola pulsación de tecla (en cualquier lugar, no solo en editores que convierten tabuladores en espacios).
La indentación es su propósito.
Respetan las necesidades de los compañeros con discapacidad visual y ciegos.

Al usar tabuladores en nuestros proyectos, permitimos la personalización del ancho, lo que puede parecer innecesario para la mayoría de las personas, pero es esencial para las personas con discapacidad visual.

Para los programadores ciegos que usan pantallas Braille, cada espacio representa una celda Braille. Por lo tanto, si la indentación predeterminada es de 4 espacios, la indentación de tercer nivel desperdicia 12 valiosas celdas Braille incluso antes de que comience el código. En una pantalla de 40 celdas, que es la más utilizada en portátiles, esto es más de una cuarta parte de las celdas disponibles que se desperdician sin ninguna información.