Directrices de codificación para desarrolladores de WP Staging

Si quieres participar en el desarrollo de WP Staging, familiarízate con las siguientes directrices de codificación y buenas prácticas.

Usa PSR https://www.php-fig.org/psr/.
Usa la sintaxis de array corta [].
Usa camelCase para los nombres de variables.
Usa StudlyCaps para los nombres de clases.
Usa guiones bajos en los nombres de archivos y carpetas.
Evita las condiciones inline.
¡Usa abreviaciones con moderación! No uses ninguna abreviación que no haya sido aprobada por el equipo y no inventes las tuyas propias que no sean comúnmente conocidas al nombrar propiedades o métodos.
Los nombres de clases, métodos y propiedades deben explicar exactamente su propósito.

Código limpio

El coste total de mantener código desordenado se acumula con el tiempo.
Es muy difícil reconstruir un sistema heredado desde cero. La refactorización y las mejoras incrementales suelen ser el mejor camino.
En bases de código desordenadas, tareas que deberían llevar horas pueden tardar días o semanas.
Tómate el tiempo necesario para ir rápido.
El código limpio hace una cosa bien. El código malo intenta hacer demasiado.
El código limpio está bien probado.
Al leer código bien escrito, cada función hace prácticamente lo que esperabas.
Si no estás de acuerdo con un principio que alguien con décadas de experiencia enseña, considera su punto de vista antes de descartarlo.
El código se lee mucho más de lo que se escribe.
El código más fácil de leer es más fácil de cambiar.
Deja la base de código mejor de como la encontraste (la Regla del Boy Scout).

Comentarios y docBlocks

Los comentarios pueden mentir. Pueden ser incorrectos desde el principio o pueden ser precisos al principio y quedar desactualizados con el tiempo a medida que el código relacionado cambia.
Usa comentarios para describir por qué algo está escrito de una determinada manera, no para explicar qué está ocurriendo.
Los comentarios a menudo pueden evitarse usando variables con nombres claros y extrayendo secciones de código en funciones con nombres claros.
Añade un prefijo consistente a tus comentarios TODO para facilitar su búsqueda. Revisa y limpia periódicamente tus comentarios TODO.
No uses docBlocks simplemente por usarlos. Los comentarios que describen qué hace un método, qué argumentos recibe y qué devuelve son a menudo redundantes en el mejor de los casos y engañosos en el peor.
Los comentarios deben incluir toda la información y el contexto relevante que necesitará quien los lea. No seas vago ni perezoso al escribir un comentario.
Los comentarios de diario y los comentarios de autor de archivo son innecesarios gracias al control de versiones y git blame.
No comentes código muerto. Simplemente elimínalo. Si crees que lo necesitarás en el futuro, para eso existe el control de versiones.
Comenta tanto como sea necesario, pero lo menos posible. Si escribes un método y sientes la fuerte necesidad de añadir un comentario, generalmente el nombre del método no es lo suficientemente claro o el código hace más de una cosa. En ese caso, considera refactorizar antes de escribir un comentario.

Estilo de código

Espacios en operadores binarios

Los operadores binarios ‘=’ y ‘=>’ deben estar rodeados de espacios. Hay una opción de autoformato en los ajustes de estilo de código del IDE que te permite alinear las asignaciones de valores de clave así:

$array = [
    $var    => 'foo',
    $varvar => 'foo'
];

$var     = 1;
$var100  = 100;
$var2000 = 2000;

Es un truco útil para hacer que porciones más grandes de código similar sean más fáciles de leer.

Condiciones Yoda

Hemos decidido no usar condiciones Yoda por facilidad de lectura.

No recomendado:

if ( true === $var ) {}

Recomendado:

if ( $var === true ) {}

Invocación de funciones/constantes nativas

La invocación nativa es una técnica que consiste en añadir una barra invertida (\) delante de la invocación de funciones/constantes para acelerar la resolución. De esta forma, PHP no necesita comprobar si la función/constante pertenece al espacio de nombres o es nativa.

Hemos decidido no usar la técnica de invocación de funciones/constantes nativas por facilidad de lectura y para evitar errores en nuestra base de código.

Sin embargo, en algunos casos está permitido usarla con cuidado y de forma razonada.

No recomendado:

if ( \is_array($var) ) {}
if ( \PHP_SAPI === 'cli') {}

Recomendado:

if ( is_array($var) ) {}
if ( PHP_SAPI === 'cli') {}

Espacios de nombres y nombres de clases

Según los principios de la Programación Orientada a Objetos (POO), los nombres de clases deben ser sustantivos, ya que representan objetos o conceptos del sistema. Esto ayuda a que el código sea más legible y comprensible para otros desarrolladores.

Sin embargo, vale la pena señalar que algunos lenguajes de programación, incluido PHP, permiten usar verbos como nombres de clases. En estos casos, el verbo generalmente indica que la clase representa una acción o comportamiento en lugar de un objeto.

Por ejemplo, una clase llamada «Mailer» podría representar un objeto que envía correos electrónicos, mientras que una clase llamada «SendMail» podría representar un comportamiento que envía correos. Aunque el uso de verbos como nombres de clases está técnicamente permitido, puede dificultar la lectura y comprensión del código, y generalmente se desaconseja en favor del uso de sustantivos.

Solo se permiten los caracteres a-z, A-Z y 0-9 para los nombres de espacios de nombres y clases.
Los espacios de nombres generalmente se escriben en UpperCamelCase, pero se permiten variaciones para nombres bien establecidos y abreviaciones.
Los nombres de clases siempre se escriben en UpperCamelCase.
El nombre de clase sin calificar debe tener sentido por sí solo, incluso sin el espacio de nombres.
El propósito principal de los espacios de nombres es la categorización y el orden.
Los nombres de clases deben ser sustantivos, nunca adjetivos.
El nombre de las clases abstractas debe comenzar con la palabra «Abstract»; los nombres de clases de aspectos deben terminar con la palabra «Aspect».

Nomenclatura incorrecta de espacios de nombres y clases:

Nombre de clase completo	Nombre sin calificar	Observaciones
WPStaging\Framework\Session\Php	Php	La clase no representa PHP
WPStaging\Framework\Cache\Backend\File	File	¡La clase no representa un archivo!
WPStaging\Framework\Session\Interface	Interface	No permitido, «Interface» es una palabra reservada
WPStaging\Framework\Controller\Default	Default	No permitido, «Default» es una palabra reservada
WPStaging\Framework\Objects\Manager	Manager	Solo «Manager» es demasiado vago

Nomenclatura correcta de espacios de nombres y clases:

Nombre de clase completo	Nombre sin calificar	Observaciones
WPStaging\Framework\Util\FileSystem	FileSystem	Es el FileSystem
WPStaging\Framework\Cache\Backend\FileBackend	FileBackend	Un backend de archivo
WPStaging\Framework\Session\SessionInterface	SessionInterface	Interfaz para una sesión
WPStaging\Framework\StandardController	StandardController	El controlador estándar
WPStaging\Framework\ObjectManager	ObjectManager

Casos límite en la nomenclatura de espacios de nombres y clases:

Nombre de clase completo	Nombre sin calificar	Observaciones
WPStaging\Framework\Mvc\ControllerInterface	ControllerInterface	La interfaz pertenece a todos los controladores del subespacio de nombres Controller
WPStaging\Framework\Mvc\Controller\ControllerInterface		Mejor
WPStaging\Framework\Cache\AbstractBackend	AbstractBackend	En realidad esta clase pertenece a los backends
WPStaging\Framework\Cache\Backend\AbstractBackend		Mejor

Métodos

Los nombres de métodos deben describir claramente qué hace el método, por lo que deben comenzar con un verbo como doSomething, makeSomething, isSomething, hasSomething.

Todos los nombres de métodos se escriben en lowerCamelCase. Para evitar problemas con diferentes sistemas de archivos, solo se permiten los caracteres a-z, A-Z y 0-9 en los nombres de métodos; no uses caracteres especiales.

Haz que los nombres de métodos sean descriptivos, pero también concisos. Los constructores siempre deben llamarse __construct(), nunca uses el nombre de la clase como nombre de método.

myMethod()

someNiceMethodName()

betterWriteLongMethodNamesThanNamesNobodyUnderstands()

singYmcaLoudly()

__construct()

Propiedades y variables

Una variable debe ser un sustantivo o adjetivo y nunca un verbo. Almacena algo y debe explicar qué contiene.

No uses la palabra clave getSomething para una propiedad. El get está reservado para getters y setters y para métodos que hacen algo explícitamente y donde no hay una palabra clave mejor que get.

Los nombres de variables se escriben en lowerCamelCase y deben ser:

Autoexplicativos.
No abreviados más allá de lo reconocible, sino más largos si eso aclara su significado.

El siguiente ejemplo muestra dos variables con el mismo significado pero nombres diferentes. Seguramente estarás de acuerdo en que las versiones más largas son mejores.

Buena nomenclatura de variables

$singletonObjectsRegistry

$argumentsArray

$aLotOfHtmlCode

renderHTMLtoScreen

Mala nomenclatura de variables

$sObjRgstry

$argArr

$cx

Como excepción especial, puedes usar nombres de variables como $i, $j y $k para índices numéricos en bucles for cuando su significado sea evidente a primera vista. Pero incluso en ese caso, deberías intentar evitarlos.

i18n, sprintf(), esc_html_* y gettext()

Siempre usa primero las funciones gettext() y envuélvelas dentro de sprintf() cuando haya parámetros en una cadena traducible.

Incorrecto:

esc_html_e(sprintf('There are %1$d monkeys in the %2$s'), $number, $string), 'text-domain');

Correcto:

// Correcto (multilínea):

sprintf(
	/* translators: number of monkeys, location. */
	__( 'There are %1$d monkeys in the %2$s', 'text-domain' ),
	(int) $number,
	esc_html( $string )
);

// Correcto (una línea):

/* translators: number of monkeys, location. */
printf( __( 'There are %1$d monkeys in the %2$s', 'text-domain' ), intval( $number ), esc_html( $string ) );

Si usas printf o sprintf, las comillas simples (‘) alrededor de la cadena son obligatorias porque las comillas dobles («) harán que PHP interprete $s como la variable s, que no es lo que queremos.

Para estandarizar con la herramienta de traducción de wporg, debe incluir el marcador de posición del traductor.

/* translators: %s: name */
sprintf(esc_html__('string %s to translate', 'text-domain'), esc_html($string));

/* translators: %1$s = name1, %2$s = name2 */
sprintf(esc_html__('string %1$s to translate for %2$s', 'text-domain'), esc_html($string1), esc_html($string2));

Leer más: https://developer.wordpress.org/plugins/internationalization/how-to-internationalize-your-plugin/#variables

Condiciones If Else

Evita las condiciones inline si requieren corchetes adicionales y sentencias if else, o si tienen más de varios estados a comparar.

De lo contrario, está bien escribirlas inline o en condiciones de retorno anticipado separadas.

Malo:

return ((!$this->isWindowsOs() && is_executable($fileName))) && is_writable($fileName) || ($this->isWindowsOs()) && is_writable($fileName);

Bueno:

if (!$this->isWindowsOs && is_executeable && is_writeable()) {
     return true;
}

if ($this->isWindowsOs && is_writeable()) {
  return true;
}

return false;

Acciones y filtros

Usa constantes para declarar el nombre del filtro; el nombre de la constante debe respetar el patrón FILTER_*.
Siempre comienza el nombre de un filtro con wpstg, usa puntos para el espacio de nombres como wpstg.backups.listing_table, donde listing_table es el nombre del método donde se usa esa acción.

Por ejemplo:

// Declarar const para el filtro
const FILTER_CLONING_UPDATE_ACTIVE_PLUGINS_FILTER = 'wpstg.cloning.update.active_plugins'

y luego

apply_filters(self::CLONING_UPDATE_ACTIVE_PLUGINS_FILTER, $activePlugins);

Almacenar datos en wp_options

Usa constantes para declarar el nombre de la opción; el nombre de la constante debe respetar el patrón OPTION_*.
Siempre comienza el nombre de una opción de tabla con wpstg, separa las palabras con guiones bajos como wpstg_backup_database_settings. No olvides añadir la nueva opción al uninstall.php.