Como añadir comentarios en CSS

Alguna vez hemos hablado en SiloCreativo de la importancia de comentar nuestro código para el futuro dentro de las recomendaciones para escribir un mejor CSS. Y aunque a corto plazo dejar un comentario o anotación explicando para que sirve lo que estamos haciendo nos puede parecer una pérdida de tiempo, a medio plazo te aseguro que no es así.

Vaya por delante que esto es extensible a todos los lenguajes de programación, ya sean en las hojas de estilos en CSS (que es de lo que vamos a hablar en este artículo) o en los archivos HTML, JS o PHP. Comentar es muy importante para que en el futuro nosotros mismos o algún compañero maquetador o programador pueda interpretar y entender algunas decisiones que se tomaron en el pasado.

Pero vayamos primero al grano, ¿Cómo agregamos comentarios en CSS?

Comentar en CSS

Todo comentario en CSS vendrá marcado por dos caracteres de apertura /* y otros dos caracteres de cierre */ según se explica en la especificación CSS2. Todo lo que se incluya dentro de esta apertura y cierre no será interpretado por el navegador.

#commentform textarea {
	height: 100px; /* Smaller field for mobile. */
	border-top: 1px solid #d8d8d8;
}

En el ejemplo anterior agregamos un comentario en linea junto con un par propiedad-valor para indicar el propósito de esa regla, en este caso que el textarea sea menor en mobile.

Pero también podemos agregar comentarios CSS en bloques y ocupando varias líneas. Esto es muy útil si queremos destacar o separar secciones en el nuestra hoja de estilos y poder acceder a ella de una forma visual gracias al minimapa de los editores de código (por ejemplo Visual Code).

/**
 * 02. TIPOGRAPHY
 *
 * -------------------------------------------------------------------
 */

html {
	font-size: 100%;
}

Una vez dentro del editor, estos bloques de comentarios CSS son fácilmente identificables y muy útiles para saltar de uno a otro o bien para incluir palabras claves que usaremos como anclas cuando realicemos una búsqueda.

¿Cuando debemos comentar en CSS?

Agregar comentarios a nuestra hoja de estilos durante la fase de desarrollo no debería importarnos demasiado. Líneas como «Esta sección falta por hacerse» o «pendiente de clases definitivas en el HTML» son comunes en esta fase, ya que el sitio todavía no está en producción y dichas anotaciones no están visibles al usuario.

Una vez superada el estado de desarrollo, debemos limpiar todos esos comentarios CSS de tareas por hacer y dejar únicamente aquellos que nos aportan un valor a futuro. Podemos distinguir algunos tipos de comentarios.

• Comentarios aclaratorios: sirven para explicar un detalle o valor concreto. Por ejemplo, la equivalencia en pixeles de una declaración rem o los dispositivos que queremos recoger en una media query CSS.
• Comentarios para definir bloques o áreas de declaraciones: Lo que comentábamos antes, a modo de separador entre bloques de código. Por ejemplo, un encabezado para la el header y otro para el footer.
• CSS deshabilitado temporalmente: si hay algunos valores de tu hoja de estilos que se van a desactivar temporalmente (por ejemplo CSS para un banner de Navidad), entonces podemos optar por comentarlo en lugar de borrarlo, ya que su uso o no-uso lo entendemos como temporal. Aunque esté comentado, el archivo CSS seguirá pesando lo mismo, por ello no uses esta opción para lograr CSS más ligero.
• Créditos y versiones: ¿Quién ha maquetado esto? ¿Cuál es su correo o web de contacto en caso de que tenga algún problema? ¿Qué versión tiene este archivo? ¿Cuál es su licencia? Todas estas cuestiones se pueden resolver fácilmente con una sección comentada (al principio o al final) donde se indiquen todos estos datos.

La importancia de comentar en CSS

Comentar en CSS nos aporta muchos beneficios. El más evidente es poder explicar nuestro código para así ahorrar tiempo en su interpretación en un futuro, ya no solo por parte de un tercero sino por nosotros mismos. ¿Habéis mirado CSS escrito por vosotros mismos de hace un par de año? ¿Sois capaces de entender la lógica en todo? Pues eso…

Por otro lado, muchas veces los equipos encargados de un proyecto cambian, ya sea porque el cliente ha decidido contratar a otra agencia o bien porque dentro del propio proyecto la persona encargada del CSS ha sido sustituida. Nos encontramos por tanto con el caso del proyecto heredado y el rompecabezas para descifrar el código CSS. Al final somos compañeros de profesión, y cuando más fácil nos lo pongamos entre nosotros, mas vamos a poder crecer. Por ello, comenta tu código también para ese futuro compañero que podría heredar tu proyecto.

Y tu ¿sueles comentar el código? ¿dejas los comentarios cuando subes el sitio a producción? ¿cuál es tu criterio para comentar en CSS?