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?
¡Hola, Ricardo!
Muy buena entrada, me han parecido muy interesantes tus reflexiones sobre la necesidad de comentar CSS. Pero te escribo porque querría discutir un poco esa «necesidad» y ver si podríamos hacerlo mejor.
Como ya sabes, yo estoy más enfocado al desarrollo en PHP y JavaScript, así que es posible que lo que diga no tenga mucho sentido… pero vamos a probar de todas formas 😇
En una entrada reciente del blog (https://neliosoftware.com/es/blog/clean-code-consejos-desarrollador-wordpress-2/) hablé de un libro que leí sobre cómo escribir mejor código. Uno de los consejos que daba era, precisamente, evitar los comentarios. Tal y como comentaba el autor, hay que escribir el código de tal forma que él mismo sea quien «explique» qué hace (en mi entrada verás un ejemplo bastante claro de esto, en la sección con la medalla de bronce).
Entonces mi pregunta es: ¿No podemos hacer lo mismo en CSS? ¿No podemos confiar en vars, custom properties, custom media queries, etc para dar nombre y sentido a nuestro CSS sin depender de los comentarios? (Estoy pensando en algunas de las cosas que hay en CSSNext…)
¡Un saludo y gracias!
Hola David!
eso sería lo ideal, que el código se explicara solo, nos ahorramos los comentarios y de camino aligeramos el peso de los archivos.
El problema que veo en CSS con respecto a PHP y JavaScript es que la semántica que podemos conseguir para explicar lo que hacemos reside en gran medida en los selectores, pues las propiedades y valores (
font-size: 1rem
) se explican por si solos. ¿Y cómo componemos esos selectores? Pues dependemos del HTML y de los identificadores y clases que contengan (u otros atributos). Aquí la necesidad de comentarios en CSS queda subordinada en gran medida a cómo esté estructurado el HTML, y en los casos donde no es posible cambiar el HTML, como en proyectos heredados, la necesidad de comentarios se hace inevitable 🙁Dicho esto, si tuviéramos control desde el principio del proyecto sobre el HTML y CSS si veo muy factible (y recomendable) lo que comentas. Importantísimo aquí el punto 5 de nombrar clases (https://www.silocreativo.com/consejos-escribir-mejor-css/), mejor un
.alert-box
que un.boton-color-naranja
¿qué pasa si en el futuro cambiamos de color? Lo que es seguro es que seguirá siendo un elemento de alerta.Junto con esto, y no se que opinas tu, me resulta más legible y ahorraríamos comentarios si añadimos elementos HTML en los selectores CSS que pudieran generar dudas o ser poco legibles (siempre que no alteren a la selección, claro está). Por ejemplo un caso reciente:
.bg-black .widget .related > .font-small
¿Qué se estaba seleccionando y donde? Aparentemente un elemento dentro de un widget en un contenedor.bg-black
La misma selección con elementos HTML (exagerada):
footer.bg-black aside.widget ul li.related > h3.font-small
Tenemos contexto, es un widget que está en el footer donde hay una lista de relacionados y seleccionamos un h3 ¿el título de una lista de post relacionados de un widget en el footer? Pudiera ser. No se necesitaría comentarios aquí 🙂En definitiva esto que comentas es muy interesante David, y si encima podemos darle contexto con media queries y ojalá en un futuro con CSS Nesting (https://github.com/w3c/csswg-drafts/issues/2701).
Un abrazo y gracias por el comentario!
Totalmente de acuerdo con tus observaciones, Ricardo. Creo que la clave está en intentar escribir todo nuestro código asumiendo que NO existen comentarios y, por lo tanto, intentando que sea lo más legible y autoexplicativo posible. Como bien dices, CSS está un poco más limitado en este sentido que otros lenguajes… pero creo que se pueden hacer muchas cosas también. También pienso que las nuevas opciones CSS (por ejemplo, CSS Grid) permitirán crear estructuras HTML más sencillas y, como consecuencia, «mejores» (más sencillos) CSS.
CSS Nesting es algo que me encanta y que ya puedes usar si escribes CSS y lo pasas por CSS Next (http://cssnext.io/features/#nesting). Otra cosa que me gusta y que, quizás, puede ayudarte con los selectores es, precisamente, los selectores personalizados (http://cssnext.io/features/#custom-selectors); con ellos puedes darle un nombre explicativo y con intención a un carro de texto que, de otra forma, sería incomprensible.
Un abrazo, amigo.
Muy bueno lo que comentas David. En CSS Grid con la propiedad
grid-template-areas
podemos tener valores auto-explicativos y CSS Next es nuestro aliado aquí. Aunque el proyecto esté discontinuado, tenemos alternativas similares.Abrazos!