Cada designer ou desenvolvedor front-end tem o hábito de documentar o código CSS de uma forma diferente através dos comentários. Alguns colocam os nomes das seções, outros inserem uma descrição mais detalhada, alguns utilizam letras maiúsculas e uma sequência de caracteres para formar uma linha.
Mas em nenhum destes formatos há uma padronização. Por isto, desde 2007 três desenvolvedores alemães têm desenvolvido a especificação do CSSDoc, que eu já havia mencionado em outro artigo.
O CSSDoc é uma convenção para documentar folhas de estilo herdada do conceito de DocBlock e permite uma forma padronizada de comentar arquivos CSS, facilitando a manutenção e a organização de arquivos compartilhados em uma equipe de desenvolvimento.
O uso desta convenção ajuda a estruturar arquivos CSS adicionando informações relevantes sobre o arquivo e seu respectivo conteúdo (classes, metadata, correção de bugs, etc). Para equipes de desenvolvimento, que necessitam compartilhar um mesmo arquivo com todos os membros da equipe, o uso do CSSDoc oferece de maneira clara e padronizada as especificações técnicas e comentários que clarificam as informações contidas no arquivo.
Para quem trabalha com Java e PHP provavelmente deve conhecer o conceito de DocBlock. Ele se assemelha a um comentário comum de código, entretanto, tem uma organização específica:
Todas as especificações baseadas em DocBlock contém tags (identificadas através do @), que são propriedades do trecho de código descrito abaixo do comentário.
Os tipos de blocos de comentários do CSSDoc
O File Comment é utilizado como descrição principal do arquivo CSS, aparece apenas uma vez no arquivo e deve ser escrito no topo. Geralmente nos comentários de arquivo são descritas informações sobre a função do arquivo e alguns metadados como autor, versão, etc.
Abrem seções em arquivos CSS e podem ser utilizados diversas vezes para estruturar o código CSS. O significado de “seção” é bastante amplo e depende do designer/desenvolvedor. Algumas seções comuns em CSS são: Reset, Layout, Tipografia, entre outros.
Principais tags do CSSDoc
Os comentários em CSSDoc podem fornecer diversas informações sobre os arquivos CSS e trechos específicos de código. Algumas tags referem-se apenas a informações do arquivo e são inseridas em File Comments, mas a maioria são utilizadas em Section Comments. Exemplos de algumas das tags mais utilizadas são:
- @autor: comentário de arquivo, pode conter o nome e/ou o e-mail do autor do documento.
- @colordef: comentário de arquivo, especifica a cor (em hexa ou RGB) e pode também ser fornecido o nome da cor e sua utilização seguido de ponto-e-vírgula.
- @bugfix: comentário de arquivo e de seção, apresenta uma descrição resumida sobre um trecho de código para corrigir alguma incompatibilidade de navegador.
- @css-for: comentário de arquivo e de seção, usado em conjunto com @bugfix para especificar qual browser está relacionado com a correção feita (Ex.: @css-for IE 6).
- @section, @subsection e @subsubsection: comentários de seção, para indicar as seções de um código CSS em até 3 níveis. Quando utilizar @subsection, o bloco de comentário também deve também conter @section, e o mesmo para o @subsubsection, deve conter a @subsection e a @section.
Porque utilizar CSSDoc
A intenção desta padronização de comentários de código é fornecer uma especificação que possa ser interpretada por aplicações denominadas parsers, que geram uma documentação HTML navegável dos blocos de código comentados com CSSDoc.
O parser é uma aplicação responsável por analisar os trechos de comentários, extrair o comentário resumido, comentário longo e as tags para depois formatá-los em documentos HTML.
Esta documentação pode ser disponibilizada online, em uma intranet, extranet ou de outra forma que preferir. E dessa forma há um manual compreensível e de fácil acesso à equipe de desenvolvimento. Em 2009, Thomas Kadauke começou a desenvolver um parser open source para CSSDoc em Ruby.
E mesmo com o uso do CSSDoc você pode continuar a utilizar o comentário convencional do CSS, ele apenas não será interpretado pelo parser.
Bônus: Cheat Sheet
Desenvolvi uma Cheat Sheet (guia de referência rápida) não oficial, em inglês, sobre as principais tags do CSSDoc e os comentários de arquivo e de seção. Você pode baixá-la aqui.
Para saber mais sobre o projeto e ver outros exemplos de aplicação das tags: CSSDoc.net
