Norma de codificación

Este documento describe las normas y recomendaciones para el desarrollo de Nette. Cuando contribuya con código a Nette, debe seguirlas. La forma más fácil de hacerlo es imitar el código existente. La idea es hacer que todo el código parezca escrito por una sola persona.

El Estándar de Codificación de Nette corresponde al Estilo de Codificación Extendido PSR-12 con dos excepciones principales: utiliza tabuladores en lugar de espacios para la sangría, y utiliza PascalCase para las constantes de clase.

Normas generales

• Cada archivo PHP debe contener declare(strict_types=1)
• Dos líneas vacías se utilizan para separar los métodos para una mejor legibilidad.
• La razón para usar el operador de cierre debe estar documentada: @mkdir($dir); // @ - directory may exist
• Si se usa un operador de comparación de tipo débil (ie. ==, !=, …), debe documentarse la intención: // == to accept null
• Puede escribir más excepciones en un archivo exceptions.php
• En las interfaces no se especifica la visibilidad de los métodos porque siempre son públicos.
• Cada propiedad, valor de retorno y parámetro debe tener un tipo especificado. En cambio, para las constantes finales, nunca se especifica el tipo porque es obvio.
• Deben utilizarse comillas simples para delimitar la cadena, excepto cuando el propio literal contiene apóstrofes.

Convenciones de denominación

• Evite utilizar abreviaturas a menos que el nombre completo sea excesivo.
• Utilice mayúsculas para las abreviaturas de dos letras, y pascal/camel para las abreviaturas más largas.
• Utilice un sustantivo o una frase nominal para el nombre de la clase.
• Los nombres de clase deben contener no sólo especificidad (Array) sino también generalidad (ArrayIterator). La excepción son los atributos PHP.
• Las constantes de clase y los enums deben usar PascalCaps.
• Las interfaces y clases abstractas no deben contener prefijos o postfijos como Abstract, Interface o I.

Envolturas y llaves

La Norma de Codificación Nette corresponde a la PSR-12 (o Estilo de Codificación PER), en algunos puntos la especifica más o la 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 los distintos tipos de sentencias import de use
• el tipo de retorno de una función/método y la llave de apertura están siempre en líneas separadas:

	public function find(
		string $dir,
		array $options,
	): array
	{
		// method body
	}

La llave de apertura en una línea separada es importante para separar visualmente la firma de la función/método del cuerpo. Si la firma está en una línea, la separación es clara (imagen de la izquierda); si está en varias líneas, en PSR las firmas y los cuerpos se mezclan (en el centro), mientras que en la norma Nette permanecen separados (a la derecha):

Bloques de documentación (phpDoc)

La regla principal: nunca duplique información de la firma como el tipo de parámetro o el tipo de retorno sin ningún valor añadido.

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

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

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

El bloque de documentación de una propiedad que sólo contenga 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 un método:

• Comienza con una breve descripción del método.
• Ninguna línea vacía.
• Las anotaciones @param, una por línea.
• La anotación @return.
• Las anotaciones @throws, una por línea.
• Pueden utilizarse las anotaciones @internal o @deprecated.

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

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

Tabulaciones en lugar de espacios

Las tabulaciones tienen varias ventajas sobre los espacios:

• el tamaño de la sangría es personalizable en editores y web
• no imponen al código el tamaño de sangría preferido por el usuario, por lo que el código es más portable
• se pueden teclear con una sola pulsación (en cualquier lugar, no sólo en editores que convierten los tabuladores en espacios)
• la indentación es su propósito
• respeta las necesidades de los compañeros invidentes o con problemas de visión

Al utilizar tabuladores en nuestros proyectos, permitimos personalizar la anchura, lo que puede parecer innecesario para la mayoría de la gente, pero es esencial para las personas con deficiencias visuales.

Para los programadores ciegos que utilizan pantallas braille, cada espacio está representado por una celda braille y ocupa un espacio valioso. Así, si la sangría por defecto es de 4 espacios, una sangría de 3er nivel desperdicia 12 celdas braille antes de que comience el código. En una pantalla de 40 celdas, que es la más utilizada en los ordenadores portátiles, eso es más de una cuarta parte de las celdas disponibles desperdiciadas sin ninguna información.