Share
Cuando se trata de escribir código, sin importar el idioma o la plataforma que se esté utilizando, los desarrolladores tendemos a dividirnos sobre cuánto o qué poco debemos comentar nuestro código..
Por un lado, hay algunos que creen que el código debería autodocumentarse. Es decir, debe estar escrito lo suficientemente claro como para que no necesite comentarios.
Por otro lado, algunos creen que todo debe ser comentado. Es decir, debería haber comentarios para cada clase, cada función, cada bloque y cada línea..
Luego, por supuesto, están los que caen en el medio. De hecho, solo algunos desarrolladores comentan. áreas de su código que puede ser confuso en lugar de elegir el enfoque de todo o nada descrito anteriormente.
Cuando se trata de escribir código para WordPress, tenemos los estándares de codificación de WordPress para proporcionar un estándar mediante el cual deberíamos escribir nuestro código; sin embargo, no proporciona un caso sólido a favor o en contra de los comentarios de código.
En esta serie de artículos, voy a presentar un caso. para Código de comentarios. Específicamente, voy a explicar por qué son importantes, una recomendación sobre cómo hacerlo en el contexto de los archivos estándar requeridos de WordPress (para temas y complementos) y sobre cómo hacerlo para archivos HTML, hojas de estilo y JavaScript. archivos.
Antes de ver las distintas partes que conforman un proyecto de WordPress, creo que es importante discutir por qué los comentarios de código son importantes. Claro, la mayoría de nosotros sabemos que es para proporcionar una breve explicación de lo que está pasando con el código, pero las implicaciones son mayores que eso.
A pesar del hecho de que tenemos estándares por los cuales debería Estando escribiendo nuestro código basado en WordPress, algunos desarrolladores los tratan como "recomendaciones", por no hablar de aquellos que ni siquiera son conscientes de ellos. Independientemente de lo bien (o mal) que escribas tu código, sigue siendo código.
Después de todo, si fuera fácil de entender, no se llamaría código (y no necesitaríamos comentarios).
No creo que debamos escribir comentarios de código solo con otros en mente, tampoco. Creo que deberíamos escribirlos para nosotros mismos tanto. Cuando vuelve a visitar el código por primera vez después de que haya transcurrido una cantidad de tiempo significativa, lo más probable es que se haya convertido en un mejor programador, haya adquirido algunas técnicas nuevas y / o haya pasado de la forma en que solía escribir el código. Por lo tanto, puede ser difícil discernir lo que intentabas hacer.
Y si es difícil para el autor del código seguir, ¿qué esperanza hay para otros desarrolladores que contribuyen, extienden o mejoran el código??
En última instancia, los comentarios deben escribirse tanto para nosotros como para otras personas que puedan interactuar con nuestro código. Deben ser claros, concisos y deben proporcionar toda la información necesaria que un desarrollador necesite saber para trabajar con la sección de código dada. Esto incluye cualquier información que haga referencia al código en otro archivos (ya sea del lado del servidor o del lado del cliente), también.
Dicho esto, me gustaría cubrir algunas razones y estrategias para comentar todos los archivos que forman parte de la creación de un tema, complemento o aplicación de WordPress..
Dependiendo de su proyecto, los archivos que debe incluir varían. Para los propósitos de este artículo, asumo que estás incluyendo archivos PHP, archivos HTML, hojas de estilo y archivos JavaScript simplemente para asegurarte de que todas las bases estén cubiertas. En este artículo, analizaremos el lenguaje del lado del servidor, es decir, PHP, y en el siguiente artículo, revisaremos los idiomas del lado del cliente.
Cuando se trata de comentar nuestros archivos PHP, hay varios requisitos que debemos seguir:
Aparte de esto, realmente se requieren muy pocos comentarios, por lo que obviamente hay espacio para mejorar.
Cuando se trata de comentar código en PHP, en realidad hay una forma sugerida de hacerlo: PHPDoc. Similar a los estándares de codificación de WordPress, PHPDoc es un estándar para comentar (o documentar) el código PHP. Proporciona una serie de convenciones que se aplican a WordPress, pero un subconjunto de las cuales veo que se usa regularmente.
WordPress soporta dos tipos de archivos de plantillas:
Cuando se trata de documentar archivos de plantilla, independientemente de qué tipo de plantilla, siempre trato de proporcionar información de encabezado que define el nombre del archivo, el propósito del archivo, el paquete, o el tema o el complemento, del cual forma parte. Y cuánto tiempo ha existido en el proyecto..
Por ejemplo:
/ ** * Nombre de la plantilla: Proyectos destacados * * La plantilla utilizada para el área 'Proyectos destacados' de la página de inicio. Recorre el tipo de publicación 'Proyectos destacados' y extrae las tres entradas más recientes. * * @package Project Theme * @since 1.0 * /
Como pueden ver, les he facilitado la información necesaria. Nombre de la plantilla para el archivo, pero también he dado una breve descripción de lo que está sucediendo dentro del archivo. También he usado el @paquete y @ya que Directivas para ayudar a dar más claridad..
los @paquete Directiva, al menos en el contexto de WordPress, representa el nombre del tema o complemento del cual este archivo en particular es parte.
los @ya que directiva representa cuánto tiempo ha existido la plantilla en el proyecto. En el caso anterior, obviamente ha estado en el proyecto desde su lanzamiento inicial, pero no es raro que se agreguen archivos a medida que el tema o el complemento maduren, por lo que aparece un número de versión diferente como este valor..
Debido a la naturaleza de los archivos de plantillas básicas, como el índice, la página, las plantillas de archivos, etc., no es necesario definir una "Nombre de la plantilla,"pero la descripción, el paquete y las directivas siguen siendo relevantes.
Documentar funciones es muy similar a documentar plantillas. Aunque no requieren una etiqueta específica, como "Nombre de la plantilla"- todavía deben incluir una descripción del propósito de la función y la @ya que directiva.
También hay dos directivas adicionales que una función puede incluir opcionalmente:
Accentsconagua
@param que describe el tipo y la descripción de un parámetro que la función acepta@regreso que describe el tipo y descripción de lo que devuelve la funciónPor supuesto, las funciones no siempre aceptan parámetros y las funciones no siempre devuelven valores, por lo que estas dos directivas son opcionales.
Suponiendo que tiene una función que es compatible con las dos directivas anteriores, aquí es cómo debe esperar que aparezca la documentación:
/ ** * Inserta programáticamente una página en la base de datos. * * @param $ title El título de la página. La variante en minúscula también sirve como la barra de la página. * @param $ template_name El nombre del archivo de plantilla ubicado en el directorio 'templates'. * @return El ID de la página que se creó * @since 1.0 * /
Para obtener más información sobre cada una de estas directivas, puede revisar las etiquetas PHPDoc; sin embargo, puede ver cuán útil puede ser esto para trabajar en un tema o un complemento, ya que le cuesta mucho tener que discernir lo que usted u otro desarrollador intentaban lograr con una función determinada.
Aunque existen pocas recomendaciones o estándares reales para documentar bloques de código, sigo creyendo que es útil, especialmente cuando se trata de bucles o condicionales más complicados..
Todo esto se puede demostrar en el siguiente ejemplo: Supongamos que necesitamos configurar una consulta personalizada para recorrer los metadatos posteriores y luego eliminarlos si se encuentra una clave y / o un valor determinados. Esto requeriría los siguientes pasos:
Este ejemplo documentará tanto las líneas simples como las condicionales. Primero, echemos un vistazo al código fuente y luego revisaremos lo que está haciendo justo después:
// Configurar argumentos para recuperar todas las publicaciones publicadas $ argument = array ('post_type' => 'post', 'post_status' => 'publish', 'numberposts' => -1)); // Crea una instancia de la consulta $ posts_query = new WP_Query ($ argumentos); // Si se encuentran publicaciones, recórrelas si ($ posts_cuerpos-> have_posts ()) while ($ posts_query-> have_posts ()) $ posts_query-> the_post (); / * * Para cada pieza de meta que se encuentre, almacene sus valores en * la $ meta_key y $ meta_value para que podamos verificarlo. * / foreach (get_post_meta (get_the_ID ()) as $ meta_key => $ meta_value) / * * Puede haber varias claves de metadatos (como tweet_url_0, tweet_url_1) * por lo que necesitamos verificar si el 'tweet_url' está ubicado en la $ meta_key * * Si es así, podemos eliminar los metadatos de la publicación * / if (false! = Strstr ($ meta_key, 'tweet_url')) delete_post_meta (get_the_ID (), $ meta_key); // terminar si // terminar foreach // terminar mientras // terminar si // Restablecer la consulta personalizada para no interferir con ninguna otra consulta o The Loop wp_reset_postdata (); Idealmente, los comentarios anteriores deberían proporcionar toda la documentación y la explicación necesarias para comprender lo que sucede en el código. Quizás lo único que puede requerirse es la comprensión de la strstr función.
El punto clave que estoy tratando de hacer con el código anterior es que si estamos documentando líneas individuales, entonces es mejor seguir con la convención de una sola línea, es decir, la // - pero si estamos escribiendo un comentario que abarca varias líneas, siempre es mejor usar el comentario de varias líneas, es decir, el / * * /.
Note también que no todas las líneas tiene ser comentado. Más bien, los bloques (o trozos) de código pueden explicarse en un comentario de varias líneas que documenta lo que va a suceder en el siguiente código fuente.
Por supuesto, esto no es una forma estándar o preferida de hacer las cosas. Es simplemente una estrategia que he visto usada, que aprecio y que uso yo mismo..
Si terminas siguiendo las convenciones establecidas en PHPDoc, entonces hay una serie de utilidades que pueden generar páginas de documentación para tu trabajo. Podría decirse que la herramienta más popular es phpDocumentor.
En resumen, phpDocumentor es una utilidad que recorrerá su código fuente en busca de comentarios en código PHPDoc con formato correcto (específicamente en clases y funciones), y luego generará un conjunto de páginas con estilos que capturan la información en sus comentarios.
Esto hace que el envío de documentación orientada al desarrollador con su aplicación sea muy fácil.
A lo largo de este artículo, he explicado por qué creo que los comentarios de código deberían ser algo que todos los desarrolladores deberían incluir en su código. Aunque el Códice de WordPress define un conjunto básico de comentarios requeridos para nuestro trabajo y / o para interactuar con la aplicación de WordPress, obviamente hay más trabajo que podemos hacer para mejorar la claridad de nuestro código..
La cosa es que solo hemos cubierto la mitad. Entonces, en el siguiente artículo, veremos cómo documentar el marcado, JavaScript y los estilos..
@paquete Directiva@ya que Directivastrstr