Contenido

Comentarios en los CSS ¿Como?

31 oct

+ 15

Hablando con el gran Daniel Mota (IceBeat) nos asalta una duda:

¿De que forma añadir comentarios a nuestros CSS?

Está claro que cada vez más se está separando el diseño de la estructura y que por ello se está convirtiendo en un lenguaje independiente y que debería estar comentado, lejos quedan ya aquellos <h1 style="color:red;"> a los que les sobra cualquier tipo de comentario. Ahora las estructuras complejas y que sin la posibilidad de acceder a la estructura HTML pueden hacer muy dificil de mantener.

#header {}
	#header h1{
 		color: red;
	} 

Está claro que sin saber que es #header, puede ser dificil mantener este código CSS. Así que viendo este código, creo que más que necesario añadir comentarios a nuestros CSS, pero ¿como?. Una pregunta no muy trivial ya que hemos de tener en cuenta que los CSS navegan hasta el cliente lo que nos limita en cuanto a tamaño se refiere, más que nada por que con según que criterios de comentarios podemos hacer que estos ocupen más que el propio código CSS. Pero por otro lado, tenemos una forma clara de saber que es cada estilo de los que estamos hablando…

Hay muchas webs que promueven el uso de comentarios en CSS y pretenden llegar a consenso global para usar la estructura Javadoc con ella:

Ejemplo

/**
* @style       Standard Layout
* @media       screen
* @version     1.0
* @author      Franky
* @copyright   Franky’s pwn comp-a-ni
* @licensor    da customa
* @layout      in pixels:
*              |            788            |
*              | 10  |      768       | 10 |
*              | 10  | 27 |    741    | 10 |
*/
 [...]
/**
* @section reset
* @see     …
* @see     http://meyerweb.com/eric/thoughts/2007/05/01/reset-reloaded/
*/
 [...]
/**
* @section layout
* @todo    margins an parent anpassen
*/

¿Que os parece? ¿exagerado?¿Necesario?

  • Es curioso, yo también he hecho ese mismo tipo de comentarios, y de hecho cuando solo hago los .tpl siempre pongo este tipo de comentarios y es más añado uno de los arboles de capas(estilos):

    /*
    //////////////////////////////////////
    arbol de capas:
    body
    |—logo
    |—contenido
    . |—navegacion(solo es una lista)
    . |—cuerpo
    . |—caja_unoDdos
    . |—caja_dosDdos
    . |—banner
    . |—menus_semana
    . |—proveedores
    . |—cocina_autor
    . |—listado_noticias
    . |—noticia
    .
    |—info

    //////////////////////////////////////
    */

  • Pufff… vaya tela, si ya pierdo tiempo co muchas cosas, imagina comentar una css de las de 30kbs…

  • A mi me parece interesante, pero lo que yo hago normalmente es tener una copia del .css en local con todo comentado y una lista de cambios realizados.

    Y subo al FTP el .css limpio de polvo y paja, no es muy ortodoxo pero…

  • Es demasiado!, yo solo uso /* menu */, /* navbar */, cosas asi.

    OT: Te falta la e en “eMail (no será publicado) (requ*rido)”

  • Pienso igual, es una burrada ese comentario

    yo siempre uso
    /*** structura ***/

    hay que pensar que cuanto más grande sea nuestro fichero css peor.

  • Estoy de acuerdo con que es bastante el comentario “tan explicado”. Yo lo hago solo en casos donde mi función se limita a crear TPL(templates) para que luego otro los integre.
    Comentarlo de ésta manera lleva unos minutos(15/20) al final de maquetarlo todo y sirve para que no pierdas tiempo(10mn ó +) cada vez que tengan que venir a preguntarte porque no se rompe algo, o porque al poner la clase, no se como las demás.
    Aunque hay que reconocer que algunos ni siquiera se han molestado en abrir el css, será porque nadie tiene la costumbre de “comentar nada”

  • Pues parece que soy el único que ve este sistema de comentarios “más o menos” práctico e incluso necesario.

    Por 2 motivos:

    1) Si programamos para nosotros, dentro de 1 año, podremos leer el código y entender por que hicimos eso en ese elemento concreto.

    2) Si programamos con más gente, ayudamos a entender nuestro código que generalmente es dificil de entender por los demás.

    Por experiencia, puedo decir que por muchos comentarios que se pongan, nunca son suficientes.

    El tema del peso del CSS, nos pone en una encrucijada, ya que el peso es un factor a tener en cuenta en nuestros diseños. Por eso usar un parseador que elimine los comentarios de nuestro CSS antes de que se ponga en producción podría ayudarnos a aligerar ese peso, disponiendo siempre de un documento documentado (xD).

  • Está de más… con comentar lo de /** estructura **/ ya basta.

  • Yo prefiero documentar la CSS aparte para no recargar el fichero.

  • Interesante artículo.
    El asunto de llevar el estándar javaDoc a Css lleva su rato, y en mi opinión tiene sus ventajas.
    En mi experiencia, cuando se trabaja en equipo, los comentarios pueden hacer una gran diferencia en la productividad y en evitar explicar lo mismo a distintas personas.
    Súmale a eso el hecho de trabajar en layouts con grilla, y agrégale el hecho de que un solo miembro del equipo entiende Css y tendrás un problemón.

    Puede parecer demasiada documentación, pero para los desarrolladores Java es algo conocido. Lamentablemente, aún no existe ninguna forma medianamente automatizada para hacer estos comentarios (como si la hay para el javaDoc), lo que hace la tarea bastante penosa; y pese a que es posible optimizar el peso del css y limpiar el código cuando se va a producción, todavía hay mucho trabajo a mano.

    En suma, creo que hay que darle tiraje a la chimenea. Imagino que en algún momento, los tipos detrás de IDE’s, pensarán en los sufridos que hacen css y saldrán con algo útil =)

  • Desde mi punto de vista es algo que no es impresindible… trankilamente podriamos hacer nuestro css sin eso…

    saludos,

    Lucas.

  • yo uso para mis css solo comentarios de estructura como dijeron algunos; /* cuerpo */ . /* header */ . /* sidebar */ blabla

    creo que todo lo demas es prescindible si los datos estan ordenados y aparte
    contando con que despues de la aclaracion de que vienen los estilos para /* sidebar */, supongamos, las clases van a tenr algun tipo de identificador, como por ej

    #sidebar {} #sidebar .header h1 {} y asi

    saludos.

  • Comentar el código en su justa medida siempre es buena práctica. En primer lugar para sosiego del propio autor que tiene que trabajar con volúmenes de ficheros, complejidades o periodos de tiempo no triviales. Y en segundo lugar para beneficio del desarrollo o mantenimiento compartido.

    En mi caso, suelo trabajar con un proyecto “fuente” en el que comento rigurosamente tanto las hojas CSS, como los archivos de script. Pero luego dispongo de una tarea automatizada que “compila” una versión para despliegue del proyecto y, entre otras cosas, compacta dichos archivos (o incluso fusiona algunos de ellos) con algún “minifier” como YUI Compressor.

Comentar

#

Me reservo el derecho de eliminar y/o modificar los comentarios que contengan lenguaje inapropiado, spam u otras conductas no apropiadas en una comunidad civilizada. Si tu comentario no aparece, puede ser que akismet lo haya capturado, cada día lo reviso y lo coloco en su lugar. Siento las molestias.