CSSDOC: documentazione con i commenti CSS

Short link

CSSDOC è un interessante tentativo di utilizzare la documentazione generata dai commenti in forma di metadati, esattamente come avviene per JavaDoc e DocBlock. Nonostante le buone, anzi ottime premesse, il progetto non ha di fatto raggiunto il grande pubblico degli sviluppatori web. Le cause sono da ricercarsi più nella natura dei CSS che non nella resistenza da parte degli sviluppatori. Vediamo perchè.

Uso di CSSDOC

Usare il seguente blocco di commenti è semplice:


/** 
  * Comment with Tags 
  * 
  * This DocBlock comment has tags. 
  *
  * @author Mina Margin 
  * @version 1.0 
  * @see http://mina.blogsaroundthe.net/ 
  */

Partendo dalla bozza ufficiale, si nota come il codice di cui sopra sia stato esteso in modo da coprire la casistica dei possibili usi nei CSS.

Per esempio, si può definire la palette di colori usata nel foglio di stile:


/**
  *
  * @colordef rgb(24,59,68); Dark Satin; Lighter Shadow 
  * @colordef rgb(12,47,56); Darker Satin; Shadow 
  * @colordef rgb(255,0,0); Red 
  * ... 
*/

O specificare che si sta usando un hack o una soluzione ad un bug per un browser specifico:


/** 
  * My CSS Workaround 
  * 
  * @workaround italic bug 
  * @affected Internet Explorer v6 to v7 (Windows)
  */

In altre parole, la sintassi dei commenti usati per la documentazione dei linguaggi di programmazione è stata adattata al contesto dei CSS.

Pregi e limiti di CSSDOC

Il merito di questo progetto è sicuramente quello di cercare di standardizzare il trend dei commenti CSS usati come metadati in modo da avere un'uniformità ed una coerenza indispensabili per una applicazione pratica a gradi progetti (specie quelli in cui si opera in team).

Il limite maggiore, invece, è quello di non tener conto della natura dei CSS: i CSS non sono un linguaggio di programmazione e quindi tutto ciò che proviene da quest'àmbito incontra molte difficoltà per divenire produttivo in questo linguaggio.

In tal senso è sicuramente più indicato l'approccio di esperti come Douglas Bowman, che usano i commenti CSS più per organizzare i fogli di stile che non per estrarne metadati.

In conclusione, un esperimento che ha mancato il suo appuntamento con l'adozione di massa proprio per aver trascurato l'aspetto più importante dei CSS: la semplicità.

L'autore

Gabriele Romanato, sviluppatore web full stack specializzato in siti, applicativi web ed e-commerce con Node.js e PHP.