Share
En esta serie, estamos profundizando en los Estándares de codificación de WordPress, específicamente los estándares de codificación de PHP, para evangelizar y entender cómo se debe escribir el código de WordPress de calidad..
A pesar de que esto está documentado en el Manual del desarrollador de WordPress, creo que hay algo que decir para entender la razón detrás de por qué Algunas cosas son como son.
Recuerde: nuestro objetivo final es asegurarnos de que estamos escribiendo código que cumpla con los estándares de codificación para que, junto con otros desarrolladores, podamos leer, comprender y mantener más fácilmente el código para temas, complementos y aplicaciones creadas. encima de WordPress.
En esta publicación, veremos cómo manejar las convenciones de nomenclatura y los argumentos de función..
Antes de dedicar tiempo a desarrollar los puntos descritos en los estándares de codificación, es importante comprender el papel que desempeñan las convenciones de nomenclatura en la escritura de código, independientemente de la plataforma con la que esté trabajando..
En última instancia, las convenciones de nomenclatura, independientemente de si son para clases, funciones, variables, atributos o argumentos, deberían ayudar a explicar el propósito al que sirven..
Con eso, me refiero a que los nombres de clase normalmente deben ser sustantivos, las funciones deben ser verbos, y las variables, los atributos y los argumentos deben explicar el propósito que tienen dentro del contexto de la clase o función en la que se definirán. Se trata de hacer que el código sea lo más legible posible..
Así como las Normas de Codificación establecen:
No abrevie nombres de variables no necesariamente; Dejemos que el código sea inequívoco y auto documentado..
Esta es una buena regla de oro. sin importar ¿De qué parte del código es en el que estás trabajando?.
Cuando se trata de trabajar con WordPress, no es probable que encuentres clases a menos que estés haciendo una de estas dos cosas:
Si simplemente estás trabajando en el tema, es más probable que trabajes con un conjunto de funciones; hablaremos de ellas momentáneamente..
Pero para aquellos que trabajan con complementos o sus propias bibliotecas, es importante recordar que las clases normalmente deben ser sustantivos, deben representar el propósito que encapsulan e idealmente deben hacer una cosa y hacerlo bien..
Por ejemplo, si tienes una clase llamada Local_File_Operations entonces puede ser responsable de leer y escribir archivos. No debería ser responsable de leer y escribir archivos, así como, por ejemplo, de recuperar archivos remotos..
De acuerdo con los estándares de codificación de WordPress, las clases deben seguir las siguientes convenciones:
Simple a la derecha?
Prácticamente hablando, esto se vería como el siguiente:
Accentsconagua
clase Local_File_Operations clase Remote_File_Operations clase HTTP_Request clase SQL_Manager Para reiterar: las clases también deben ser sustantivos y deben describir el único propósito al que sirven.
Como se mencionó anteriormente, si las clases son sustantivos que idealmente representan una sola idea o un único propósito, entonces sus métodos deberían ser las acciones que pueden tomar. Como tales, deberían ser verbos, deberían indicar qué acción se tomará cada vez que se les llame.
Además, los argumentos que aceptan también deben tener en cuenta el nombre de la función. Por ejemplo, si una función es responsable de abrir un archivo, entonces su parámetro debe ser un nombre de archivo. Debido a que nuestro objetivo debe ser lo más fácil posible para leer el código, debe leer algo como "que el administrador de archivos local lea el archivo con el siguiente nombre de archivo".
En el código, esto puede parecer algo como esto:
// La clase de definición de clase Local_File_Manager public function open_file ($ filename) // Implementación de la función // Cómo usaríamos este código $ file_manager = new Local_File_Manager (); $ file_manager-> open_file ('foo.txt'); Por supuesto, esto todavía no cubre cómo Las funciones deben escribirse dentro del contexto de desarrollo de WordPress. Las Normas de Codificación establecen:
Use letras minúsculas en los nombres de variables, acciones y funciones (nunca
el caso de Carmel). Separar palabras a través de guiones bajos. No abrevie nombres de variables no necesariamente; Dejemos que el código sea inequívoco y auto documentado..
La primera parte de la convención es bastante fácil de entender; sin embargo, creo que los desarrolladores tienen una propensión a tomar atajos cuando pueden. "Ah," pensamos, "$ str tiene sentido aquí, y $ numero tiene sentido aquí ".
Por supuesto, siempre hay algo peor: algunos desarrolladores recurren al uso de caracteres individuales para sus nombres de variables (lo que generalmente solo es aceptable dentro de los bucles).
Así como las Normas de Codificación establecen: No abrevie nombres de variables no necesariamente. Deje que el código sea inequívoco y autodocumentado..
Ahora, la verdad es que el código solo puede ser inequívoco hasta cierto punto. Después de todo, por eso se llama código, ¿verdad? Es por esto que creo que los comentarios de código deberían ser usados generosamente..
De todos modos, la conclusión es escribir minúsculas los nombres de sus métodos, evitar todas las carcasas de camellos, separarlas por espacio y ser lo más específica posible al nombrar sus variables..
En realidad, los nombres de variables no son muy diferentes de los nombres de funciones que representan un solo valor o una referencia a un objeto en particular. Las convenciones de nomenclatura siguen lo que se espera
Otra convención que usan algunos desarrolladores es lo que se conoce como Notación Húngara, que es donde el tipo de valor que almacena la variable es prefijado delante de la variable.
Por ejemplo:
$ str_firstname $ i_tax o $ num_tax $ arr_range Sinceramente, los estándares de codificación no dicen nada sobre esto. Por un lado, creo que esto hace que el código sea más limpio en el ámbito general del código, pero hay muchos desarrolladores a los que no les gusta la notación húngara..
Dado que las convenciones de codificación no dicen nada acerca de ellos, no me atrevo a recomendarlos ya que quiero estar lo más cerca posible de los estándares. Como tal, tengo que recomendar que es mejor seguir los estándares de codificación.
Para mantener la coherencia con el tema de hacer que nuestro código sea lo más legible y auto-documentado posible, tiene sentido que lo revisemos a través de nuestro código fuente hasta los archivos en los que vamos a crear nuestro tema, complemento o solicitud.
Según las Normas de Codificación:
Los archivos deben nombrarse descriptivamente usando letras minúsculas. Los guiones deben separar las palabras..
De acuerdo con nuestro ejemplo anterior, digamos que estamos trabajando con Local_File_Operations entonces el archivo sería nombrado class-local-file-operations.php.
Suficientemente fácil.
A continuación, si estás trabajando en un plugin llamado Instagram_Foo entonces el archivo debe ser nombrado instagram-foo.php; sin embargo, vale la pena señalar que si usa algún tipo de método avanzado para desarrollar sus complementos, como mantener el archivo de clase de complemento en su propio archivo y luego cargarlo con otro archivo, entonces su estructura de archivos puede ser:
class-instagram-foo.phpinstagram-foo.phpDónde instagram-foo.php es responsable de cargar el class-instagram-foo.php. Por supuesto, esto solo tiene sentido si está usando OOP al escribir sus complementos de WordPress.
Cuando se trata de pasar argumentos de funciones, es importante recordar que si los nombres de funciones describen las acciones que realiza la clase, entonces el argumento debería representar en qué opera realmente la función..
De los Estándares de Codificación:
Prefiere valores de cadena a solo
ciertoyfalsoal llamar a funciones.
Dado que los valores booleanos pueden ser poco claros cuando se pasan valores a una función, hace difícil determinar exactamente qué está haciendo la función.
Por ejemplo, usemos el ejemplo anterior de una manera ligeramente diferente:
// La clase de definición de clase Local_File_Manager public function manage_file ($ filename, true) if (true) // Abre el archivo else // Borre el archivo // Cómo usaríamos este código $ file_manager = nuevo Local_File_Manager (); $ file_manager-> manage_file ('foo.txt', true); Es más difícil de entender que, digamos, algo como esto:
// La clase de definición de clase Local_File_Manager public function open_file ($ filename) // open the file public function delete_file ($ filename) // delete the file // Cómo usaríamos este código $ file_manager = new Local_File_Manager (); $ file_manager-> open_file ('foo.txt'); $ file_manager-> delete_file ('foo.txt'); Además de eso, recuerde que los argumentos que se pasan a las funciones siguen siendo variables en sí mismos, por lo que están sujetos a las convenciones de nombres de variables que hemos detallado anteriormente..
Hemos examinado los convenios de nomenclatura y los argumentos de función en los estándares de codificación. Esperamos que esto haya ayudado a proporcionar no solo una guía sobre cómo mejorar ciertos aspectos de su código de WordPress, sino también a explicar las razones 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 contexto de trabajar con cadenas en el desarrollo de WordPress.
Ahí es una diferencia en la forma en que PHP las interpreta y existen condiciones en las que debe usar una sobre la otra y la revisaremos en el siguiente artículo.
