Los estándares de codificación de WordPress: Reuniéndolo todo
() translation by (you can also view the original English article)
Cuando se trata de escribir una serie de entradas de blog, uno de los aspectos más desafiantes como lector es mantenerse realmente al día con cada entrada que se publica.
Incluso si logras mantenerte al día, las entradas que superan las 1.000 palabras, especialmente las que incluyen código, pueden tomar un tiempo que muchos de nosotros no tenemos especialmente cuando se trata de hacer malabarismos con nuestra vida laboral, nuestras vidas en el hogar, nuestros pasatiempos y otras cosas.
Así que con el fin de asegurarte de que la información presentada a lo largo de esta serie todavía se presenta de una manera digerible, pensé que experimentaría haciendo un resumen de toda ella. De esa forma, aquellos de vosotros que os hayáis perdido un artículo o no hayáis tenido tiempo para sentaros y leer cada artículo, todavía podréis obtener la esencia de cada punto mencionado a lo largo de los artículos.
Dicho esto, echemos un vistazo a todo lo que cubrimos al revisar los Estándares de codificación de WordPress.
Los estándares de codificación de WordPress
En términos generales, el propósito de toda esta serie es ayudar a aclarar los Estándares de codificación de WordPress para que aquellos que no hayan oído hablar de ellos, aquellos que no los conozcan, o aquellos que no los hayan estado siguiendo estén mejor equipados para escribir temas, plugins y aplicaciones de WordPress.
Para ello, profundizamos en una serie de aspectos diferentes de las Normas de Codificación a lo largo de seis artículos diferentes que resaltan principios, mejores prácticas y cosas que debes evitar.
A continuación, hemos resumido cada uno de los artículos, así como los puntos clave y lo que vale la pena destacar sobre el tema en cuestión. Por supuesto, si te quedas deseando más información, puedes volver al artículo de la serie (enlazado en la parte superior de este artículo) para leerlo en su totalidad.
1. Convenciones de nomenclatura y argumentos de función
Convenciones de nomenclatura
Cuando se trabaja con clases, funciones, variables, atributos o argumentos, las convenciones de nomenclatura deben ayudar a explicar el propósito al que sirven.
Por ejemplo, las clases suelen ser sustantivos y los nombres de función normalmente son verbos. En última instancia, se trata de asegurarse de que el código sea legible y mantenible.
Directamente de los estándares de codificación:
No abreviar los nombres de variables de forma innecesaria; que el código sea inequívoco y se documente por sí mismo.
Pero este principio en particular vale la pena seguirlo de forma independiente a dónde estés trabajando en el código.
Argumentos de función
No olvides que cuando se trata de pasar argumentos de función, es importante recordar que si un nombre de función describe la acción que toma dentro del contexto de la clase, el argumento debe representar aquello sobre lo que la función está operando realmente.
Prefiere los valores de cadena que sean solo
true
yfalse
al llamar a funciones.
Esto significa que los argumentos de función deben ser valores claros, cadenas o números, ya que los valores booleanos a menudo no son claros y no indican necesariamente qué acción debe realizar la función.
2. El uso de comillas simples y comillas dobles
Cuando se trata de trabajar con cadenas en WordPress, por lo general es una cuestión de trabajar dentro de los matices de la manipulación de cadenas PHP. Por tanto, en este artículo, revisamos cómo maneja PHP las comillas (tanto simples como dobles) y cómo afecta a nuestro desarrollo de WordPress.
Comillas simples
La forma más fácil de definir una cadena en PHP consiste en envolverla con comillas simples (es decir, el carácter ').
Al igual que con la mayoría de los lenguajes de programación, existen maneras de escapar los caracteres para que puedas escribir una cadena literal. Por ejemplo, si quisieses escribir: "String's in PHP are easy," (Las cadenas en PHP son fáciles), como una cadena, podrías hacer lo siguiente:
'String\'s in PHP are easy.'
Las barras diagonales inversas indicarán a PHP que escriba la comilla simple en lugar de terminar la cadena real. La segunda cosa a tener en cuenta es que si tienes una variable, esta no se reemplazará si se coloca entre comillas simples.
Comillas dobles
Las comillas dobles dentro de PHP funcionan un poco diferentes. Específicamente:
Si la cadena está entre comillas dobles ("), PHP interpretará más secuencias de escape para caracteres especiales.
Esto significa que si incrustas una variable dentro de una cadena PHP con dobles comillas, la variable será interpretada y su valor será insertado en lugar de la variable antes de ser mostrada en la pantalla.
Cadenas y WordPress
Dado que gran parte del trabajo realizado en WordPress también incluye la escritura de marcado dentro de una cadena PHP, es mejor colocar esas cadenas entre comillas simples para que los atributos del elemento HTML se puedan incluir entre comillas dobles.
Pero hay momentos en los que es más preferible usar comillas dobles, especialmente cuando necesitas evaluar una variable.
El mejor consejo que se puede ofrecer aquí es conocer cómo funcionan las comillas simples y las comillas dobles dentro de PHP, y luego utilizarlas adecuadamente en función de tu caso de uso.
3. Sangría, espacio utilizable y espacios finales
Recuerde: El espacio en blanco mejora la legibilidad del código y, como desarrolladores, uno de nuestros objetivos principales debe ser asegurarse de que el código que estamos escribiendo no solo sigue un estándar predefinido, sino que también está atendiendo a otros desarrolladores para facilitar la legibilidad y la capacidad de mantenimiento.
Sangrías
En cuanto a la sangría, no hay nada realmente nuevo, especialmente si estás familiarizado con los idiomas de estilo C. La mayoría de las veces, crearás una sangría cada vez que inicies un nuevo bloque.
- Tus funciones llevarán sangrías dentro de la clase
- Tus condicionales y conmutadores/casos y otros bloques llevarán sangrías dentro de sus funciones
- Tus bucles llevarán sangrías dentro de sus funciones, dentro de sus condicionales, y así sucesivamente
Ten en cuenta que los estándares de codificación tienen reglas sobre las tabulaciones y los espacios:
Tu sangría debe reflejar siempre una estructura lógica. Utiliza tabulaciones reales, no espacios, ya que esto permite la mayor flexibilidad entre los clientes.
Esto es especialmente útil en la comunidad de código abierto.
Uso del espacio
Los espacios deben colocarse en los siguientes lugares:
- Después de las comas
- En ambos lados de los operadores lógicos (es decir,
||
,&&
, y!
) - En ambos lados de los operadores de comparación (es decir,
<
,>
,==
,==
, etcétera) - En ambos lados de los operadores de asignación (a saber
=
) - En ambos lados del paréntesis de apertura y cierre de funciones, condicionales, bucles, etcétera.
- Cuando una variable se pasa como índice de una matriz, pero no cuando se pasa un valor literal (como una cadena o un entero)
Espacios finales
Esta es una de las convenciones más simples a seguir. Honestamente, lo más probable es que tu IDE o editor de preferido tenga esta función integrada, o exista un plugin disponible que te permita hacerlo automáticamente.
Si no es así, deberías poder activar la capacidad de ver las tabulaciones, los espacios, los retornos de carro, etcétera para que puedas identificar fácilmente dónde están los espacios finales. Y cuando los veas, elimínalos.
4. Estilo de corchetes, expresiones regulares y etiquetas PHP
En esta sección, echamos un vistazo a por qué es importante el estilo. También definimos exactamente cómo los estándares y convenciones de codificación definen la manera en la que aplicamos estilo a nuestro código.
Estilo de corchetes
En términos generales, las reglas son simples:
- Los bloques de una sola línea pueden omitir los corchetes
- Los bloques multilínea siempre deben incluir corchetes
- Cuando tengas condicionales multilínea excesivos, considera la posibilidad de dividir los condicionales en tus propias funciones para minimizar el bloque
Estos son particularmente comunes si vienes de otros lenguajes de estilo C; sin embargo, al igual que WordPress tiene matices sutiles que otros idiomas no tienen, vale la pena resaltarlos aquí.
Expresiones regulares
PHP ofrece una variedad de maneras de trabajar con expresiones regulares, aunque WordPress recomienda que solo usemos un puñado de las funciones disponibles.
Las reglas para trabajar con expresiones regulares en PHP en WordPress son las siguientes:
- Utiliza las funciones
preg
que ofrece PHP - No utilices el conmutador
\e
ofrecido por PHP, utiliza en su lugarpreg_replace_callback
.
Concretamente, recomiendo estar familiarizado con las siguientes funciones:
Además, ten en cuenta que preg_replace_callback es una forma de invocar una función cuando una expresión regular ha encontrado una coincidencia.
Etiquetas PHP
Hay una regla general muy simple para el uso de etiquetas PHP en el desarrollo para WordPress:
- Nunca utilices etiquetas PHP abreviadas
Esto significa que nunca debes abrir un archivo o una declaración PHP en línea con <?
o con <?=
. Naturalmente, todas las instrucciones PHP en línea deben finalizarse con la etiqueta de cierre ?>
.
Además del estándar de codificación definido anteriormente, yo también añadiría lo siguiente:
- Evita añadir una etiqueta PHP de terminación en archivos PHP puros.
La razón de esto se mencionó literalmente en el artículo asociado:
Pero si estás escribiendo un plugin o un archivo de aplicación que es 100% PHP, entonces no hay necesidad de agregar una etiqueta de terminación al final del archivo. El analizador será capaz de detectarlo por sí mismo, y si incluyes una etiqueta de terminación, entonces potencialmente podrías dejar espacio en blanco al final del archivo que podría provocar todo tipo de problemas cuando llegue el momento de activar el plugin.
5. Las condiciones del operador ternario y yoda
Cuando se trata de escribir código basado en WordPress, los Estándares de codificación indican que debemos esforzarnos por la legibilidad:
En general, la legibilidad es más importante que la inteligencia o la brevedad.
Algunos desarrolladores consideran que el operador ternario está un poco en desacuerdo con este principio en particular específicamente porque es una forma más de escribir una instrucción if/else
. Aún así, el operador ternario es una opción viable cuando se trata de escribir condicionales simples y así se indica en los Estándares de codificación de WordPress.
El operador ternario
En primer lugar, para aquellos que no estén familiarizados, el operador ternario es una forma simplificada de escribir una instrucción condicional if/else
. Normalmente se usa solo cuando el condicional es de la forma más simple y solo cuando existe un único if
y un único bloque else
.
1 |
$uses_gasoline = 'hybrid' == $car_type ? false : true; |
2 |
echo $uses_gasoline; |
Algo importante a notar: el operador ternario está comprobando si es cierto (en lugar de falso, obviamente).
Condiciones de Yoda
Las condiciones de Yoda se refieren a la reversión de las comparaciones de variable a valor que realizamos al escribir código WordPress. Esto es así, de acuerdo con las Normas de codificación, porque:
En el ejemplo anterior, si omites un signo igual (admítelo, sucede incluso con los más experimentados de nosotros), obtendrás un error de análisis, porque no puedes asignarlo a una constante como
true
. Si la instrucción fuera al revés( $the_force = true )
, la asignación sería perfectamente válida, devolviendo1
, haciendo que la instrucción if se evalúe comotrue
y podrías estar persiguiendo ese error durante un buen tiempo.
Claro, es discutible, pero es parte del estándar y vas a ver esto usado a través del núcleo de WordPress, de los temas, de los plugins, de los artículos y mucho más.
6. Consultas de base de datos y formato de consultas SQL
Por lo tanto, en resumen, si la API no cumple con lo que necesitas, entonces $wpdb
podría ser tu mejor opción, pero te recomiendo usarla solo si ya has agotado el resto de tus opciones.
Consultas de bases de datos
En WordPress, existe una serie de APIs que nos permiten crear nuestras propias consultas sin necesidad de escribir SQL. Entre algunas de estas APIs se incluyen:
Es importante familiarizarse con lo que ofrece la API para que puedas saber si existe o no una función o un objeto disponible para usar antes de saltar directamente a la escritura de tus propias consultas.
Consultas SQL
Las APIs no pueden predecir todos los casos en los que necesitamos escribir nuestras consultas de base de datos. Y en esas situaciones, WordPress proporciona un objeto que nos permite interactuar directamente con la base de datos: $wpdb
.
Nos permite:
-
SELECT
(seleccionar) variables, filas, columnas y resultados genéricos -
INSERT
(insertar) filas -
UPDATE
(actualizar) las filas existentes
Y nos permiten recuperar los datos en un formato con el que prefiramos trabajar: una matriz, un objeto o un único valor (en algunos casos), e incluso nos permite protegernos de la inyección sql.
Pero recuerda:
Si debes tocar la base de datos, entra en contacto con algunos desarrolladores publicando un mensaje en la lista de correo wp-hackers. Es posible que quieran considerar la creación de una función para la próxima versión de WordPress que cubra la funcionalidad que deseas.
Conclusión
Como mencioné anteriormente, puede ser difícil mantenerse al día con una serie de artículos, especialmente aquellos que involucran código. Con ese fin, quería experimentar proporcionando un resumen de la serie que todavía de suficiente información a aquellos que no hayan tenido la oportunidad de mantenerse al día con toda la serie, pero que aun así estén interesados en los temas en cuestión.
Así que si esta estrategia o tipo de artículo en particular es algo que disfrutas, avísame y tal vez podamos seguir haciéndolo para otras series; de lo contrario, si no hay daño no hay ninguna falta, estoy conforme de cualquier manera.
A pesar de todo, espero que la serie haya ayudado a explicar una serie de áreas diferentes de los Estándares de Codificación de WordPress que usted ha perdido previamente, malinterpretado, o no ha gruñido completamente hasta la lectura de estos artículos.