Pour les commentaires longs qui documentent des sections ou composants entier du document, on utilises des commentaires multilignes DocBlock-esque qui répondent à la règle des 80 caractères de large..
Voici un exemple réel du CSS qui style le page header sur CSS Wizardry:
/** * The site’s main page-head can have two different states: * * 1) Regular page-head with no backgrounds or extra treatments; it just * contains the logo and nav. * 2) A masthead that has a fluid-height (becoming fixed after a certain point) * which has a large background image, and some supporting text. * * The regular page-head is incredibly simple, but the masthead version has some * slightly intermingled dependency with the wrapper that lives inside it. */
ce niveau de détail devrait être la norme pour tout code non-trivial —description d'états, permutations, conditions, traitements.
Lors du travail au travers de multiples partials, ou d'une manière OOCSS, vous trouverez parfois que les bases de règles qui travaillent de concert ne se trouvent pas toujours dans le même fichier/endroit. Par exemple, vous pouvez avoir un objet bouton générique — qui fournit des styles purement structurels — qui doit être étendu dans un partial de niveau composant qui ajoutera un aspect cosmétique. On documente cette relation au travers des fichiers avec de simples pointeurs d'extensions d'objet.
Dans le fichier objet :
/**
* Extend `.btn {}` in _components.buttons.scss.
*/
.btn { }
Et dans votre fichier thème :
/**
* These rules extend `.btn {}` in _objects.buttons.scss.
*/
.btn--positive { }
.btn--negative { }
Ce simple petit effort peut faire beaucoup de différence pour les développeurs qui ne sont pas conscients des relations au sein d'un projet, ou qui veulent savoir comment, pourquoi et où les autres styles peuvent avoir une relation d'héritage.