J'utilise un style de commentaire docBlock où la taille est limitée à 80 caractères :
/**
* Ceci est un commentaire de style DocBlock
*
* Ceci est une description plus détaillée
* Nous limitons ces lignes pour un maximum de 80 caractères.
*
* Nous pouvons avoir des balises dans les commentaires :
*
<div class="foo">
<p>Lorem</p>
</div>
*
* Nous n'avons pas de préfixe avec une étoile pour faciliter le
* copier-coller.
*/
Vous devez documenter et commenter votre code autant que vous le pouvez, quoi qu'il arrive. Cela peut sembler trop transparent ou explicite pour vous mais peut-être pas pour un autre développeur. Chaque nouveau morceau de code doit-être documenté.
Il y a un certain nombre de techniques plus avancées que vous pouvez employer en ce qui concerne les commentaires, à savoir :
Vous ne devriez jamais qualifier vos sélecteurs, c'est-à-dire que nous ne devrions jamais écrire ul.nav {} si vous pouvez juste avoir .nav. Qualifier vos sélecteurs diminue leur rendement, inhibe le potentiel de réutilisation d'un objet sur un autre type d'élément et augmente la spécificité du sélecteur. Ce sont toutes des choses qui doivent être évitées à tout prix.
Cependant, il est parfois utile de communiquer à d'autres développeurs où vous avez l'intention d'utiliser une classe. Prenons .product-page par exemple, cette classe sonne comme si elle était utilisée sur un conteneur de haut niveau, peut-être avec html ou body, mais seulement avec .product-page il est impossible de le savoir.
Par quasi-qualification de ce sélecteur (autrement dit en commentant le sélecteur de premier plan), nous pouvons communiquer nos intentions pour cette classe :
/*html*/ .product-page {}
Nous pouvons maintenant voir exactement où s'applique cette classe, sans avoir les inconvénients de la la spécificité ou de la non-réutilisation.
D'autres exemples pourraient être: :
/*ol*/ .breadcrumb {}
/*p*/ .intro {}
/*ul*/ .image-thumbs {}
Dans ces cas, nous savons le contexte d'utilisation de ces classes sans jamais impacter la spécificité des sélecteurs
Si vous écrivez un nouveau composant, laissez certaines balises relatives à son utilisation dans un commentaire ci-dessus, par exemple:
/**
* ^navigation ^lists
*/
.nav {}
/**
* ^grids ^lists ^tables
*/
.matrix {}
Ces balises permettent à d'autres développeurs de trouver des bouts de code en recherchant une fonction, si un développeur a besoin pour travailler avec des listes ils peuvent rechercher ^lists et trouver les objets associés .nav et .matrix (et probablement plus).
Lorsque l'on travaille d'une manière orientée objet, vous aurez souvent deux morceaux de CSS (l'un étant le squelette (l'objet) et l'autre étant la peau (l'extension)) qui sont très étroitement liés, mais qui vivent dans des endroits très différents. Afin d'établir un lien béton entre l'objet et son extension nous utiliserons des pointeurs objet / extension. Ce sont simplement des commentaires comme ceci :
Dans votre feuille de style de base :
/**
* Extend `.foo` in theme.css
*/
.foo {}
Dans votre feuille de style de thème :
/**
* Extends `.foo` in base.css
*/
.bar {}
Ici, nous avons établi une relation concrète entre deux morceaux de code très distincts.
Liste des conseils →