Share
En esta serie de dos partes, analizamos cómo construir un caso para los comentarios de código. En el primer artículo, cubrimos el lado del servidor echando un vistazo a PHP. Específicamente, revisamos las convenciones de PHPDoc y cómo usarlas para documentar plantillas, funciones, líneas y bloques..
En este artículo, vamos a echar un vistazo a los idiomas del lado del cliente. Específicamente, vamos a ver HTML, CSS y JavaScript..
Aunque no hay necesariamente utilidades de documentación como phpDocumentor para todos estos idiomas, todavía hay estrategias que podemos emplear para facilitar el mantenimiento de nuestros proyectos (o ayudar a otros a contribuir con nuestros proyectos).
Cuando se trata de trabajar con WordPress, los temas y los complementos variarán en el tipo de archivos que incluyen. Los temas generalmente consistirán de HTML y CSS y probablemente algunos JavaScript, mientras que los complementos mayo solo consisten en PHP.
En el primer artículo, vimos lo que requiere WordPress para registrar los archivos de plantilla con la API, así como lo que requieren los complementos. Antes de seguir leyendo, recomiendo revisar ese artículo primero, ya que cubre la información requerida, mientras que este artículo en particular solo incluirá recomendaciones sobre lo que podemos hacer para mejorar nuestros comentarios..
La mayoría de los desarrolladores web saben cómo escribir comentarios en el contexto de HTML. Simplemente, es una cuestión de prefijar el código, ya sea una sola línea o bloque, con . Cuando se trata de escribir marcas, no es terriblemente común ver los comentarios más allá de los condicionales que puede encontrar en el cabeza elemento del documento.
Existen técnicas que podemos utilizar para hacer que nuestro código sea más fácil de mantener. Esto es especialmente útil cuando se trabaja con sistemas como WordPress porque ciertos elementos se repartirán en varios archivos.
Por ejemplo, suponiendo que está creando un tema, es probable que abra su cuerpo elemento y un elemento contenedor en el header.php plantilla y luego terminar los elementos en el footer.php modelo.
Este es un ejemplo un tanto simplificado, ya que es relativamente común, pero el principio se mantiene a través de los otros archivos..
Dicho esto, hay una estrategia simple que podemos usar para comentar nuestro código:
Los elementos HTML generalmente estarán en una de cuatro formas:
Para cada una de estas permutaciones, sigo las siguientes convenciones:
Arriba, hay un fragmento de código para un formulario que se usa para guardar opciones en el formulario de base de datos de WordPress dentro del Tablero. En este caso, normalmente dejaré un comentario al final del elemento que indica el propósito del formulario o algún otro atributo, como el atributo de acción.
Dada esa estrategia, el ejemplo anterior puede parecer algo como esto:
O:
La convención que opto por usar es usar una barra invertida (en forma normal de HTML) seguida por el propósito de la descripción del elemento para hacerme saber que estoy terminando el elemento..
Si bien esto puede no ser especialmente útil con un solo elemento aislado, he encontrado que es útil con elementos anidados, así como cuando un elemento, como un contenedor, se divide en archivos..
En el caso de que el elemento tenga una identificación, uso el siguiente comentario:
Al igual que arriba, uso una barra invertida seguida de un '#'que representa un ID en CSS seguido del nombre del valor del atributo ID. Esto me permite saber que estoy terminando un elemento con la ID dada.
Nuevamente, esto es más útil cuando un elemento existe en todos los archivos, pero también es útil cuando necesita hacer una búsqueda global en archivos de plantilla o en archivos CSS.
Cuando un elemento incluye solo una clase (o un conjunto de clases), sigo una estrategia similar a la anterior: uso una barra invertida, el indicador CSS para una clase y luego la clase (o la primera clase) en el elemento:
Suficientemente simple.
Pero, ¿qué sucede cuando el elemento incluye una identificación y una clase? Dado que las ID son únicas y los nombres de clase no lo son, siempre utilizo la ID del elemento cuando finalizo el comentario:
Tiene sentido, ¿verdad? Y el punto sigue siendo: esto hace que sea fácil saber qué elemento estoy terminando y hace que sea fácil encontrarlo en el resto de los archivos del proyecto..
JavaScript es similar a PHP, ya que admite funciones de orden superior, como funciones (y prototipos, si está escribiendo JavaScript de vainilla). Por eso, tener una convención mediante la cual documentamos nuestras funciones es útil.
La cuestión es que: WordPress incluye jQuery de manera predeterminada, por lo que es común que la mayoría de los JavaScript específicos de WordPress se escriban utilizando una combinación de JavaScript basado en jQuery y funciones basadas en vainilla como funciones.
Las siguientes estrategias han demostrado ser útiles para escribir JavaScript en WordPress:
Primero, trato de nombrar el archivo según el propósito que sirve (como navegación.js o theme.js o admin.js).
En segundo lugar, también proporcionaré una breve descripción en la parte superior de cada archivo utilizando las convenciones de PHPDoc para describir el archivo y durante cuánto tiempo ha sido parte del proyecto:
/ ** * admin.options.js * * Administra los controladores de eventos para varios elementos en la página de opciones del Panel. * * @since 1.0 * @version 3.2 * /
Para las funciones, sigo una convención similar a la anterior, ya que proporcionaré una breve descripción de la función, describiré qué acepta y qué devuelve, así como cuánto tiempo ha estado en el proyecto y la versión actual del archivo:
/ ** * La función de ayuda se activa cuando el usuario hace clic en 'Listo' o 'Intro' * cuando trabaja para guardar sus iconos sociales. * * @param $ Una referencia a la función jQuery * @param evt El evento de origen de este controlador * @returns Si el usuario pulsa Intro o Cancelar para guardar sus opciones. * @since 1.0 * @version 1.2 * /
Esto realmente no es nada más que los comentarios de código estándar que la mayoría de los desarrolladores utilizan. Existe la variación de una sola línea, la variación multilínea y el propósito al que sirven: es decir, simplemente para describir lo que está a punto de ocurrir en el código que sigue al comentario..
Accentsconagua
/ * * Si estamos viendo el ícono de la fuente RSS, deshabilite la entrada * y vincule al usuario con las opciones globales donde puede configurarla. * / if ("! == sRssUrl) $ ('# social-icon-url') .val (sRssUrl) .attr ('disabled', 'disabled'); else $ ('# social-icon- url '). removeAttr (' disabled '); // end si Hay muy poco que agregar a esto que no he cubierto en el primer artículo, pero quería mencionarlo aquí para revisar y completar..
Aunque no hay una herramienta oficial de documentación de JavaScript, jsDoc se ha convertido en una de las utilidades más comunes para documentar el código de JavaScript..
Comentar archivos CSS es decididamente mucho más fácil que trabajar con PHP o con marcado porque realmente solo hay una forma única de escribir estilos.
Es decir, usted define estilos para un elemento usando una ID o una clase:
# no-comments font-size: 24px; línea de altura: 36px; font-weight: negrita; color: # 444;
O:
.casa .sticky: antes de display: inline-block; fondo: url transparente (images / sticky.png) no-repetir; ancho: 58px; altura: 45px; contenido: ""; posición: absoluta; arriba: 26px; izquierda: -9px;
En general, no creo que necesite comentar los estilos, pero si se encuentra en una situación en la que el soporte de terminación está fuera de la pantalla, puede ser útil finalizar el estilo con un comentario como este:
# no-comments font-size: 24px; línea de altura: 36px; font-weight: negrita; color: # 444; /* #sin comentarios */
O:
.casa .sticky: antes de display: inline-block; fondo: url transparente (images / sticky.png) no-repetir; ancho: 58px; altura: 45px; contenido: ""; posición: absoluta; arriba: 26px; izquierda: -9px; / * .home .sticky: antes de * /
En este momento, el uso de lenguajes como LESS y Sass y sus respectivos preprocesadores es cada vez más popular en el desarrollo web. Una de las características más comunes de estos dos idiomas es que admiten reglas anidadas.
En este caso, creo que hay un caso mucho más sólido para el uso de comentarios. Por ejemplo:
#header #slideshow # image-list list-style: none; flotador izquierdo; margen: 0; ancho: 100%; // # lista de imágenes // #slideshow // #header
De esta manera, usted sabe qué elemento está terminando, independientemente de dónde comience el elemento en el IDE..
A lo largo de esta serie, 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. En este artículo, he discutido mis estrategias sobre cómo comento mi marca, mi JavaScript y mis estilos..
Aunque no estoy diciendo que mi camino es el solamente forma de escribir comentarios, pero es una manera: creo que incluir comentarios contribuye en gran medida a hacer que un proyecto sea más fácil de mantener para usted y sus compañeros, y creo que incluirlos en su trabajo es algo que cada desarrollador debe apuntar a.
Esperemos que esta serie haya proporcionado un caso para eso. En cualquier caso, me encantaría escuchar sus opiniones y sugerencias en los comentarios..
