Estándares de Código en WordPress: Convenciones de Nomenclatura y Argumentos de Funciones

Spanish (Español) translation by Eva Collados Pascual (you can also view the original English article)

En esta serie, estamos profundizando en las normas relativas al código para WordPress, en concreto, los estándares de código PHP, para evangelizar y entender cómo se debería escribir código de calidad en WordPress.

A pesar de que todo esto está documentado en el WordPress Developer Handbook (Manual para el Desarrollador de WordPress), creo que es preciso explicar algunos puntos para lograr entender el motivo del por qué algunas cosas son de una determinada forma.

Recuerda: Nuestra meta es asegurarnos de que estamos escribiendo código que cumpla con las normas que a él se aplican, de forma que, junto con otros desarrolladores, seamos capaces de leer, entender y mantener más fácilmente el código de los temas, plugins y aplicaciones construidas sobre WordPress.

En este artículo, vamos a ver cómo manejar la terminología y los argumentos de las funciones.

Convenciones de Nomenclatura

Antes de profundizar en los puntos destacados sobre estándares de código, es importante entender el papel que desempeñan las convenciones de nomenclatura al escribir código, con independencia de la plataforma en la que estés trabajando.

En definitiva, las convenciones de nomenclatura, ya sean para las clases, funciones, variables, atributos, o argumentos, deberían ayudar a explicar el propósito al que sirven.

Con esto, quiero decir que los nombres de las clases deberían ser en general sustantivos, las funciones deberían típicamente ser verbos y las variables, los atributos y argumentos deberían explicar el propósito al que sirven en el contexto de la clase o función que definen. Se trata de hacer el código lo más comprensible y legible posible.

Tal y como afirman los Estándares de Código:

No abrevies los nombres de las variables innecesariamente; haz que el código sea inequívoco y se documente por sí sólo.

Esta es una buena norma de base, con independencia de la parte del código en la que estés trabajando.

Nombres de Clase

No es probable que mientras trabajas con WordPress, te encuentres con clases a menos que estés haciendo una de estas dos cosas:

Que estés escribiendo una librería personalizada para trabajar con ella en un tema o aplicación
O que estés escribiendo un plugin basado en programación orientada a objetos (OOP)

Si simplemente estás trabajando con el tema, es muy probable que trabajes con un conjunto de funciones, hablaremos acerca de éstas en un momento.

Pero para aquellos que están trabajando con sus propias librerías o plugins, es importante recordar que las clases por lo general deben ser sustantivos, deben representar su propósito de forma condensada e idealmente deberían hacer una cosa y hacerla bien.

Por ejemplo, si tienes una clase que se llama Local_File_Operations sería posible que fuese responsable de la lectura y escritura de archivos. No debería ser responsable de la lectura y escritura de archivos, ni tampoco de digamos, la recuperación de archivos remotos.

Según los estándares de código para WordPress, las clases deben seguir las siguientes convenciones:

Los nombres de las clases deben usar palabras mayúsculas separadas mediante guiones bajos.
Cualquier tipo de siglas deberían estar escritas en su totalidad en mayúsculas.

Simple, ¿verdad?

Siendo prácticos, esto tendría el siguiente aspecto:

classs Local_File_Operations {}
class Remote_File_Operations {}
class HTTP_Request {}
class SQL_Manager {}

Reiteramos: las clases también deben ser sustantivos y deben describir el propósito específico al que sirven.

Nombres de Funciones

Como mencionamos anteriormente, si las clases son sustantivos que idealmente representan una sola idea o un único propósito, entonces los nombres de las funciones deberían consistir en lo que éstas sean capaces de hacer. Por tanto, deben ser verbos, deben indicar qué acción será ejecutada cuando sean invocadas.

Además, los argumentos que aceptan también deberían constituir un factor a considerar para determinar el nombre de la función. Por ejemplo, si una función es responsable de abrir un archivo, su parámetro debe ser un nombre de archivo. Puesto que nuestro objetivo debería hacer que la comprensión del código sea lo más sencilla posible, deberíamos leer por ejemplo algo así "hacer que el gestor de archivos locales lea el archivo con el siguiente nombre".

En el código, esto podría tener el siguiente aspecto:

// The class definition
class Local_File_Manager {

  public function open_file( $filename ) {
		// Function implementation
	}

}

// How we'd use this code
$file_manager = new Local_File_Manager();
$file_manager->open_file( 'foo.txt' );

Por supuesto, esto aún no explica cómo deben ser escritas las funciones dentro del entorno de desarrollo de WordPress. Los Estándares de Código indican que:

Usa letras minúsculas en los nombres para las funciones, las acciones y las variables (nunca uses guiones bajos). No abrevies nombres de variables innecesariamente; el código debe ser inequívoco y documentarse por sí sólo.

La primera parte de la convención es bastante fácil de entender; sin embargo, creo que los desarrolladores tienen propensión a tomar atajos siempre que pueden. "Ah," pensamos, "$str tiene sentido aquí y $number aquí".

Por supuesto, siempre hay casos peores, algunos desarrolladores por ejemplo, recurren al uso de caracteres aislados como nombres de variables (lo cual generalmente sólo es aceptable dentro de loops).

Tal y como los Estándares de Código establecen: no abrevies los nombres de variables de forma innecesaria. Que el código sea inequívoca y se explique por si solo tanto como sea posible.

Ahora, la verdad es que código sólo puede ser inequívoco hasta un cierto punto. Después de todo, por algún motivo se llama código, ¿no? Por este motivo, creo que los comentarios en el código deben ser utilizados con libertad.

De todos modos, lo principal es usar nombres en minúscula, evitar los guiones bajos, separar mediante espacios en blanco y ser tan específico como sea posible al nombrar tus variables.

Nombres de Variables

Los nombres de las variables realmente no difieren mucho de los nombres de las funciones, la única diferencia es que representan un solo valor o una referencia a un objeto determinado. Las convenciones de nomenclatura siguen siendo lo que cabría esperar:

Minúsculas (en lugar de los guiones bajos)
Espacios separados con guiones bajos

Otra convención que algunos desarrolladores usan es lo que se conoce como Notación Húngara, que hace referencia al lugar en el que el tipo de valor que la variable almacena lleva un prefijo delante de la variable.

Por ejemplo:

Las cadenas se representan a menudo como $str_firstname
Los nombres se escribirán como $i_tax o $num_tax
Los arrays se pueden escribir como $arr_range
… y así sucesivamente

Honestamente, los estándares de código no indican nada sobre esto. Por un lado, creo que esto hace que el código sea más limpio en su conjunto, pero hay un montón de desarrolladores a los que no les gusta la Notación Húngara.

Como las convenciones de código no dicen nada acerca de esto, estoy dudando de si recomendarlos ya que quiero permanecer lo más fiel posible a las normas. Por tanto, tengo que recomendar que es mejor seguir las normas del código.

Nombres para los Archivos

Para mantener constante el propósito de hacer el código tan legible y comprensible como sea posible, tiene sentido que extendamos esta intención a lo largo de nuestro código fuente hasta incluir los nombres de los archivos que compondrán nuestro tema, plugin o aplicación.

Según los Estándares de Código:

Los archivos deben tener nombres descriptivos usando letras minúsculas. Y las palabras deben separarse con guiones.

Para ser consecuentes con nuestro anterior ejemplo, supongamos que estamos trabajando con Local_File_Operations por tanto el archivo se llamaría class-local-archivo-operations.php.

Bastante sencillo.

Continuando, si estás trabajando en un plugin llamado Instagram_Foo, el archivo debería llamarse instagram-foo.php; sin embargo, cabe señalar que si usas alguna clase de método avanzado para el desarrollo de tus plugins, tales como mantener la clase del archivo del plugin en su propio archivo y después cargarlo usando otro archivo, entonces tu estructura podría ser:

class-instagram-foo.php
instagram-foo.php

Dónde instagram-foo.php es el responsable de cargar la class-instagram-foo.php. Por supuesto, esto sólo tiene sentido si estás utilizando programación orientada a objetos (OOP) al escribir tus plugins para WordPress.

Argumentos para las Funciones

Cuando se trata de pasar argumentos de función, es importante recordar que si los nombres de la función describen las acciones que están siendo tomadas por la clase, entonces el argumento debería representar lo que realmente está operando respecto a la función.

Según los Estándares de Código:

Dá preferencia a valores en cadena sobre simplemente true y false al invocar las funciones.

Dado que los valores booleanos pueden ser confusos al pasar valores a una función, hace que sea complicado determinar exactamente lo que hace la función.

Por ejemplo, usemos el ejemplo anterior de una manera ligeramente diferente:

// The class definition
class Local_File_Manager {

	public function manage_file( $filename, true ) {

		if ( true ) {
			// Open the file
		} else {
			// Delete the file
		}

	}

}

// How we'd use this code
$file_manager = new Local_File_Manager();
$file_manager->manage_file( 'foo.txt', true );

Es más difícil de entender que, digamos, algo como esto:

// The class definition
class Local_File_Manager {

	public function open_file( $filename ) {
		// open the file
	}

	public function delete_file( $filename ) {
		// delete the file
	}

}

// How we'd use this code
$file_manager = new Local_File_Manager();
$file_manager->open_file( 'foo.txt' );
$file_manager->delete_file( 'foo.txt' );

Además de esto, recuerda que los argumentos que se pasan a funciones siguen siendo variables en y por sí mismos, de modo que están sujetos a las convenciones de nomenclatura de las variable que hemos detallado anteriormente.

Conclusión

Hemos revisado en detalle las Convenciones de Nomenclatura y los Argumentos de las Funciones según los Estándares de Código. Esperamos que esto no sólo te haya esrvido de guía para saber cómo mejorar ciertos aspectos en tu código para WordPress, sino también te haya explicado la lógica detrás de algunas de las prácticas.

En el siguiente artículo, vamos a echar un vistazo a la importancia de las comillas simples y dobles en el entorno del trabajo con secuencias en el desarrollo con WordPress.

Son interpretadas de forma diferente en PHP y existen condiciones en las que deberías utilizar unas con preferencia sobre las otras, lo vamos a revisar en el próximo artículo.