Share
Dans le monde des CSS, la documentation est sous-utilisée. La documentation n'étant pas visible par l'utilisateur final, les clients la négligent souvent. En outre, si vous documentez votre code pour la première fois, il peut être difficile de déterminer quoi documenter et Comment pour le faire plus efficacement.
Cependant, la documentation CSS peut apporter beaucoup à votre projet: encourager de meilleures pratiques de code à faciliter l'intégration de nouveaux membres de l'équipe. Dans cet article, je vais expliquer les avantages de la documentation CSS et partager ce que mon équipe et moi-même, à Bitovi, considérons comme les meilleures pratiques pour que la documentation fonctionne pour vous - et non l'inverse. Plongeons dedans.
Il est difficile d'entrer dans le train de la documentation quand vous et votre équipe ne savez pas exactement quoi documenter ni comment vous voulez que cela fonctionne. La première étape consiste donc à convenir des conventions que vous utiliserez et de la manière dont vous devez les appliquer. Vous pouvez le faire dans un document live afin que tous les membres de l'équipe puissent contribuer. De cette manière, au fur et à mesure que votre approche change ou devient plus complète, vous pouvez la maintenir à jour. Un document Google partagé, une page wiki sur votre dépôt de code ou (encore mieux) une page sur votre «guide de style de vie» sont tous d'excellents endroits pour cela..
Regardons maintenant les «règles de base» que vous pouvez inclure.
Comprendre comment votre code est organisé permet à quiconque de se lancer directement dans l'action dès le premier jour. Une façon simple de le faire est de créer une carte de la structure de votre fichier où vous pouvez expliquer son contenu et ce qui devrait aller où. Ce faisant, prêtez une attention particulière aux endroits où il pourrait y avoir une ambiguïté. Par exemple, indiquer que le fichier «buttons.css» contient des styles pour les boutons n’est pas très utile, mais indiquer que le répertoire «custom» est l’endroit où se trouvent les styles personnalisés pour le thème peut vous faire gagner du temps..
Voici un exemple:
Project Root ├── srs ├── styles // Styles de base. Les styles placés ici doivent être disponibles n'importe où dans l'application ├── bootstrap-custom // Styles personnalisés écrasant bootstrap ├── personnalisé // Styles personnalisés créés pour l'application ├── démos // Démos pour illustrer les styles et les interactions du style guide ├── polices img // Images utilisées UNIQUEMENT dans les feuilles de style ├── variables // Variables utilisées dans le thème personnalisé └── styles.less // Importations de toutes les feuilles de style de base composants alertes └── alert.less // Styles personnalisés pour le composant d'alerte. Chaque composant a sa propre feuille de style qui permet de le personnaliser spécifiquement pour empêcher les ballonnements et les fuites de style..
En règle générale, documentez les endroits où des éclaircissements sont nécessaires. Tous les répertoires et fichiers n’auront pas besoin de documentation (comme dans l’exemple ci-dessus, «polices» s’explique de soi). Mettez-vous à la place de quelqu'un de nouveau dans le projet (ou souvenez-vous des moments où vous étiez cette personne) et fournissez les conseils que vous auriez souhaité obtenir. L'idée est de faire cela d'une manière qui ne prenne pas de temps, mais qui soit suffisamment utile pour éviter les questions répétitives..
Un autre élément clé à souligner ici est l'endroit où de nouveaux styles doivent être ajoutés et les étapes à suivre. L'exemple ci-dessus le montre bien, mais étant donné la nature héréditaire de CSS, il peut être intéressant de l'exprimer en détail..
Par exemple, dans les projets où nous avons utilisé Bootstrap en tant que framework sous-jacent, nous avons généralement trois endroits où les nouvelles règles doivent s’appliquer, en fonction de ce que le développeur essaie de réaliser. Nous avons donc ajouté un guide à la documentation comprenant trois scénarios:
Si vous voulez écraser un style défini par Bootstrap, alors:
Si vous souhaitez ajouter une nouvelle définition de style qui ne remplace pas Bootstrap et qui devrait être disponible n'importe où dans l'application, alors:
Si vous souhaitez ajouter une nouvelle définition de style pour un composant (cela signifie que celle-ci ne sera disponible que pour ce composant, quel que soit le lieu d'utilisation du composant dans l'application):
Ce guide:
Vos normes de codage ou votre guide de style CSS font référence à la façon dont votre équipe a convenu d’écrire du code CSS. Cela inclut les meilleures pratiques en matière d'écriture de code, telles que les conventions de formatage, de nommage et de syntaxe. De nombreuses entreprises ont partagé leurs méthodes de travail (cet article de CSS-Tricks contient une excellente compilation: CSS Style Guides). Je trouve utile de partager ce type d’informations de différentes manières:
Utilisez ce format pour indiquer les éléments que vous souhaitez éviter, tout en offrant une alternative viable. Cela supprime l'ambiguïté et encourage les gens à faire quelque chose de spécifique. Par exemple:
| À ne pas faire | Faire |
|---|---|
| Ne pas utiliser les tabulations pour l'indentation. | Utilisez quatre (4) espaces pour l'indentation. |
| N'utilisez pas de under_scores ou «camelCase» pour nommer des classes ou des identifiants. | Utilisez des tirets pour séparer les mots. |
N'utilisez pas les noms de classe et d'ID pour refléter la structure de balisage sous-jacente. .conteneur-span et .small-header-div sont de mauvais noms. | Pensez à CSS en termes d'objets et utilisez des noms simples comme noms. |
| N'utilisez pas d'identifiants ni de sélecteurs trop spécifiques pour le style. Utilisez-les uniquement lorsque cela est absolument nécessaire (par exemple, des contrôles de formulaire ou des ancres de page). | Utilisez des classes pour faciliter la réutilisation et réduire les conflits de spécificité de sélecteur CSS. |
Résumez vos directives en meilleures pratiques et incluez des exemples. Cela rendra chacun plus facile à lire et à comprendre. Par exemple:
| Les meilleures pratiques | Exemple |
|---|---|
| Écrire plusieurs sélecteurs sur des lignes séparées. | .btn, .btn-link |
| Inclure un espace entre le sélecteur et l’accolade ouvrante. | .sélecteur |
| Utilisez un raccourci pour les valeurs hexadécimales lorsque cela est possible. | #fff contre #ffffff |
| Écrire des valeurs hexadécimales en minuscules. | # 3d3d3d contre # 3D3D3D |
| Placez les URL entre guillemets simples. Généralement, les guillemets simples sont préférés aux guillemets doubles, car ils sont plus faciles à taper. | url ('/image.png') contre url ("/image.png") |
| Ne pas utiliser les unités pour les valeurs zéro (0), sauf pour les angles (degrés) et le temps (s ou ms). | marge droite: 0; contre marge droite: 0px; |
La manière dont un développeur écrit du code peut être très différente d’un autre. C'est pourquoi il est important que votre équipe établisse des normes de codage. Cela garantit la cohérence du code dans un projet, ce qui facilite la lecture, l'écriture et la révision. Mais assurez-vous que tout ce que vous incluez dans vos normes de codage est une pratique convenue par votre équipe..
J'ai travaillé sur un projet où nous avons inclus cela dans notre guide de style de vie. Dans le cadre du code, nous nous sommes engagés et avons poussé ces meilleures pratiques vers le repo. Ensuite, pour s'assurer que tout le monde était à bord, tous les membres de l'équipe devaient approuver la demande d'attraction avant que nous puissions la fusionner. Cela garantissait que tout le monde devait prendre le temps de l'examiner et d'en discuter.
Lorsque vous divisez vos styles en feuilles de style plus petites et plus ciblées, il est plus facile de les documenter. Vous pouvez également gagner du temps en évitant de documenter ce qui devient explicite..
Par exemple, au lieu d'avoir une feuille de style de 800 lignes avec toutes les variables que vous pouvez utiliser dans un thème, vous pouvez créer un fichier pour chacun des types de variables. Cela vous fera gagner du temps en évitant de faire défiler le fichier en essayant de trouver quelque chose! Pensez également au temps que vous pouvez économiser en évitant de mettre à jour l'index chaque fois que vous ajoutez ou renommez une nouvelle section..
/ * ------------------------------------------- * \ variables.less Index - Palette de couleurs - Typographie - Boutons - Formulaires - Mise en page - Messagerie et statut - Général - Navigation - Carrousel - Jumbotron \ * ------------------------ ------------------- * /
Un autre exemple à prendre en compte lorsque vous travaillez dans de grandes applications est le flux de travaux du modlet. Cela explique pourquoi le fait de travailler avec des fichiers plus petits organisés par composants permet de les tester et de les assembler plus facilement dans votre application..
Une bonne partie de la documentation des CSS consiste à écrire de bons CSS, et inversement. Cela signifie que même lorsque l'état de votre base de code CSS pourrait ne pas être optimal, l'application de règles de documentation peut vous aider à améliorer votre système..
C'est ici que la documentation CSS avec un guide de style en tête entre en place. L'idée sous-jacente est qu'un guide de style peut vous aider à déterminer une bonne structure pour votre CSS car pour en créer un, vous devez distinguer:
Le gros de votre code CSS devrait être composé des styles de base, car ils sont disponibles n'importe où dans l'application et affectent tous les éléments dans leur état par défaut. Les styles personnalisés doivent avoir lieu lorsque vous ajoutez des composants ayant une apparence et un comportement spécifiques, ou dans les cas où la présentation d'un élément ou d'un composant d'une page le requiert.
Un excellent moyen de capturer le fonctionnement de cette configuration spécifique dans votre application consiste à créer un plan du site avec guide de style. Une fois que vous savez à quoi ressemble un guide de style dans votre application, vous pouvez documenter des éléments dans cet esprit. Par exemple, si vous avez défini dans votre guide de style l’apparence des boutons et de la navigation, vous devez leur ajouter de nouveaux styles et de la documentation (dans «buttons.css» et «navs.css»). Mais qu'en est-il d'une navigation faite de boutons?
Avoir un guide de style peut vous aider à prendre cette décision, car vous pouvez comparer l'apparence des boutons et de la navigation, à partir d'une perspective d'affichage et de balisage. Regardons cet exemple:
Dans ce cas, il existe deux emplacements possibles pour le CSS qui définiront la navigation faite de boutons:
Accentsconagua
Une fois que vous avez décomposé vos feuilles de style en fichiers plus faciles à gérer, vous pouvez continuer cet exercice en décomposant chaque style en sections individuelles..
Pour commencer, chaque feuille de style doit au moins inclure un titre et (le cas échéant) une brève description. Le titre peut être aussi simple que le nom du fichier, avec une majuscule pour ressembler davantage à un titre (ex: «Boutons» pour la feuille de style «boutons.css»), ou le même nom que le nom du fichier, comme ce:
/ ** * icons.css * / .icon font-family: 'bitovi'; parle: aucun; style de police: normal; poids de police: normal; variante de police: normal; transformation de texte: aucune; hauteur de ligne: 1;
Je trouve que l’utilisation du nom de fichier est particulièrement utile lors du débogage du code dans le navigateur, et surtout lorsque le fichier a été compilé avec d’autres fichiers, car je peux obtenir une référence au fichier dans lequel le style vit..
Notez également que le style de commentaire que j’ai utilisé s’ouvre avec / **vs juste / *. JSDoc utilise cette convention pour analyser les commentaires à inclure dans la documentation générée automatiquement. Je recommande d'utiliser ce style, car de nombreux générateurs de guides de styles de vie utilisent le format JSDoc. Ainsi, lorsque vous serez prêt à utiliser un générateur, votre code nécessitera très peu de travail supplémentaire..
Dans tous les cas, vous pouvez utiliser d'autres styles pour désigner une section telle que:
/ * ------------------------------------------- * \ icons.css \ * ------------------------------------------- * / .icon famille de polices: 'bitovi'; parle: aucun; style de police: normal; poids de police: normal; variante de police: normal; transformation de texte: aucune; hauteur de ligne: 1;
Dans une certaine mesure, cela dépend de ce que votre équipe considère comme le meilleur moyen de faire ressortir une section. La seule exigence est d'utiliser / * au début et * / à la fin. Ce qui compte vraiment, c’est que quelle que soit l’approche que vous utilisez, vous vous en tenez à elle et l’utilisez dans votre code CSS de manière cohérente..
Si vous pensez qu'une description peut être utile dans une feuille de style particulière, ajoutez-la dans le cadre de ce premier commentaire. Par exemple:
/ ** * icons.css * * Les icônes doivent exprimer de manière simple et significative le concept de la fonction * qu'elles représentent. Lors de la conception de nouvelles icônes, veillez à éliminer toute complexité * et à suivre l'aspect linéaire et léger du jeu d'icônes. * / .icon font-family: 'bitovi'; parle: aucun; style de police: normal; poids de police: normal; variante de police: normal; transformation de texte: aucune; hauteur de ligne: 1;
Cela renforcera l’idée qu’il s’agit d’une section. Essayez également de décomposer la description en plusieurs lignes (Harry Roberts recommande 80 caractères au maximum) afin de faciliter la lecture lorsque plusieurs fichiers sont ouverts ou lus sur Github..
Après avoir ajouté un titre et une description, vous pouvez aller plus loin en décomposant les styles de la feuille de style en sections. Pour ce faire, réfléchissez à la logique d'expliquer le contenu d'une feuille de style. Par exemple, la feuille de style “buttons.css” aura généralement une section où le style par défaut d’un bouton est défini en appliquant simplement la classe. .btn. Il y aura ensuite des styles supplémentaires définissant différentes couleurs, tailles et configurations pouvant être appliquées conjointement pour personnaliser davantage son apparence et son comportement. La création de sections pour chacun de ces styles facilitera la compréhension et la recherche des nouvelles classes ou écrasements. En outre, il est moins intimidant de consulter un fichier lorsque le code est présenté dans des extraits, par rapport à un fichier long où il est difficile de savoir où commencent et se terminent les styles..
Regardons cet exemple comparatif. Tout d'abord, un bloc de code MOINS sans pour autant sections:
.label-condensed-variant (@color) &: before background-color: @color; .label border-radius: 0; font-family: @ font-family-bold; taille de police: 85%; position: relative; & .label - condensé font-size: @ font-size-xsmall; couleur: @gray; fond: transparent; padding-right: @ padding-small; & .label - primaire .label-condensed-variant (@ label-primary-bg); & .label - success .label-condensed-variant (@ label-success-bg); & .label - info .label-condensed-variant (@ label-info-bg); & .label-warning .label - variante condensée (@ label-warning-bg); & .label - danger .label-condensed-variant (@ label-danger-bg); & .label - simple font-family: @ font-family-base; taille de la police: @ font-size-xsmall - 1; couleur: @gray; bordure: 1px solid @ grey-light; rembourrage: 2px; border-radius: @ border-radius-small; text-transform: majuscule;
Et le même bloc de code avec sections:
/ ** * bootstrap-custom / _labels.less Labels * * Ecrase les styles par défaut définis par le framework bootstrap. * * / .label border-radius: 0; font-family: @ font-family-bold; taille de police: 85%; position: relative; / ** * Étiquettes condensées * * Modifie les étiquettes pour fournir une version plus petite et plus étroite avec un cercle coloré à utiliser dans les zones disposant de peu d'espace (par exemple, dans les vues de liste). * / .label & .label - condensé font-size: @ font-size-xsmall; couleur: @gray; fond: transparent; padding-right: @ padding-small; / ** * Étiquettes condensées - Couleurs * / .label-condensed-variant (@color) // Variant mixin pour définir la couleur du cercle &: before background-color: @color; .label & .label - condensed & .label - primaire .label-condensed-variant (@ label-primary-bg); & .label - success .label-condensed-variant (@ label-success-bg); & .label - info .label-condensed-variant (@ label-info-bg); & .label - warning .label-condensed-variant (@ label-warning-bg); & .label - danger .label-condensed-variant (@ label-danger-bg); / ** * Simple Labels * * Modifie les étiquettes pour fournir une version linéaire simple où les couleurs ne sont pas utilisées. * / .label & .label - simple font-family: @ font-family-base; taille de la police: @ font-size-xsmall - 1; couleur: @gray; bordure: 1px solid @ grey-light; rembourrage: @ padding-small; border-radius: @ border-radius-small; text-transform: majuscule;
C'est un excellent moyen de fournir un aperçu du contenu de la feuille de style et un élément essentiel dans les projets où, pour une raison quelconque, de longues feuilles de style sont là pour rester (vous n'êtes pas fan de ces projets, mais ils se produisent!).
Un index de feuille de style ressemble généralement à ceci:
/ ** * icons.css * * Les icônes doivent exprimer de manière simple et significative le concept de la fonction * qu'elles représentent. Lors de la conception de nouvelles icônes, veillez à éliminer toute complexité * et à suivre l'aspect linéaire et léger du jeu d'icônes. * * Index * - Icon Font * - Icon Variations * - Icon Animations * * /
Et bien que j'aime leur propreté et leur utilité, je dois admettre qu'ils peuvent être facilement oubliés, et donc dépassés. Ils sont également difficiles à mettre à jour quand ils sont longs et que vous utilisez des chiffres (alors évitez-les!)
Une autre façon d'utiliser les index consiste à laisser un générateur de guide de style effectuer le travail pour vous en consultant vos feuilles de style, en recherchant les sections que vous avez définies et en générant un index. Je développerai plus sur ce sujet à la fin de cet article.
C'est ici que réside le secret de la documentation. Il est facile de s'emballer et d'entrer dans une frénésie de documentation une fois pour ensuite l'oublier et se retrouver avec seulement une partie de votre base de code trop documentée et le reste non documenté. Comme pour tout dans la vie, le secret est de trouver l'équilibre. Documentez les domaines dans lesquels une attention est requise car il y a dépendances imprévues, ressources supplémentaires, ou notes IMPORTANTES avoir à l'esprit. Cela signifie que tous les éléments de code ne doivent pas nécessairement être documentés, mais il est certainement utile de les décomposer en morceaux et d’expliquer ce que sont ces morceaux lorsque cela est nécessaire. De cette manière, la documentation devient un outil utile faisant partie de votre flux de travail et non une réflexion après coup que vous évitez de le faire. Mais comment faites-vous exactement cela? Voici un exemple:
Supposons que vous allez implémenter le balisage et le code CSS pour le composant de carte suivant:
En regardant les dessins, vous pouvez identifier les motifs de style suivants:
Vous pouvez ensuite décomposer l’application CSS en gardant à l’esprit ces modèles et utiliser la documentation pour vous guider. Pour commencer, votre feuille de style «cards.css» peut inclure une introduction simple, comme suit:
/ ** * cards.css * * Ce sont les styles du composant carte. * * Index * - Base de la carte * - Grille de la carte * - Liste de la carte * - Carte sombre * /
Vous pouvez inclure plus d’informations utiles dans l’introduction, mais comme vous venez de commencer, quelque chose de simple vous aidera à poser le squelette de la documentation.
Ensuite, ajoutons les sections où vous travaillerez dans vos styles:
/ ** * cards.css * * Ce sont les styles du composant carte. * * Index * - Base de la carte * - Grille de carte * - Liste de cartes * - Carte sombre * / / ** * Base de la carte * / / ** * Grille de carte * / / ** * Liste de la carte * / / ** * Carte Foncé */
Avec ces sections à l'esprit, vous pouvez visualiser la structure du code. Vous savez que vous devez rendre les définitions de base de la carte suffisamment souples et indépendantes pour pouvoir facilement faire fonctionner la carte dans une version en grille, en liste ou sombre..
Alors que vous écrivez le code, vous pouvez être plus précis avec vos commentaires:
/ ** * Carte Base * * Définit l'apparence et le comportement de la carte par défaut avec ses parties principales: * - Image de la carte * - Contenu de la carte * - Pied de carte * / .card … .card__image … .card__logo … .card__content … .card__footer …
Je considère cela comme le niveau de base de la documentation que vous devez inclure car il sert de guide pour la mise en forme du code et informe rapidement de la manière dont les choses sont organisées pour la prochaine personne qui y travaille..
Le niveau suivant consiste à ajouter des commentaires spécifiques à une règle, qui peuvent être utilisés pour expliquer le fonctionnement de cette règle car elle n’est pas évidente en un coup d’œil. Par exemple:
/ ** * Card Base * * Définit l'apparence et le comportement de la carte par défaut avec ses différentes parties: * - Image de la carte * - Logo de la carte * - Contenu de la carte * - Pied de carte * / .card @media (largeur maximale: screen-xs) border: none; / * car la carte occupe 100% de l'écran du mobile * / .card__image … .card__logo … .card__content flex: 1 1 auto; / * "auto" doit être explicite pour éviter que la division ne s'effondre sous IE. * /
L'avantage de cette approche réside dans le fait que la documentation est là pour soutenir et informer la mise en œuvre au fur et à mesure, par opposition à quelque chose qui est ajouté ultérieurement..
Voici quelques exemples du framework Bootstrap montrant quand les commentaires sont utiles et quand il vaut la peine d'entrer dans les détails..
// Besoin de .dropdown-toggle depuis: last-child ne s'applique pas, // étant donné qu'un .dropdown-menu est utilisé immédiatement après .btn-group> .btn: last-child: not (: first-child) , .btn-group> .dropdown-toggle: pas (: premier-enfant) .border-left-radius (0);
Ce commentaire explique pourquoi ces styles existent et ce qu’ils font. C'est aussi court et précis que de communiquer l'idée dans une langue décontractée.
// Options de case à cocher et radio // // Afin de prendre en charge le retour d'informations de validation de formulaire du navigateur, optimisé par l'attribut // "requis", nous devons "masquer" les entrées via "clip". Nous ne pouvons pas utiliser // 'display: none;' ou 'visibilité: masqué;' comme cela cache aussi le popover. // Cacher simplement les entrées via "opacité" les laisserait cliquables // dans certains cas, ce qui est empêché par les options "clip" et "événements de pointeur". // De cette façon, nous nous assurons qu'un élément DOM est visible pour positionner le popover. // // Voir https://github.com/twbs/bootstrap/pull/12794 et // https://github.com/twbs/bootstrap/pull/14559 pour plus d'informations. [data-toggle = "buttons"] > .btn,> .btn-group> .btn input [type = "radio"], input [type = "case à cocher"]] position: absolute; clip: rect (0,0,0,0); événements de pointeur: aucun;
C’est un excellent exemple de documentation plus approfondie qui explique la logique qui sous-tend une décision de mise en œuvre et fournit des liens vers des informations supplémentaires..
En gardant à l’esprit ces meilleures pratiques, l’étape suivante consiste à incorporer un guide de style de vie dans le cadre de votre documentation. Un guide de style de vie est un document vivant qui montre les commentaires que vous avez inclus dans votre code et qui sont structurés comme un site Web. Vous pouvez ainsi naviguer dans la documentation séparément du code source..
Ce qui fait la force des guides de style de vie, c'est que la documentation elle-même vit avec le code et peut être facilement mise à jour à mesure que votre code change, ce qui lui permet de rester synchronisé et pertinent. L'avantage supplémentaire est que vous pouvez mettre cette documentation à la disposition des autres membres de votre équipe qui pourraient ne pas interagir directement avec le code (concepteurs, chefs de produit ou ingénieurs d'assurance qualité, par exemple). Ces membres de l’équipe trouveraient également utile de savoir comment l’interface utilisateur prend forme.
Dans un guide de style de vie, vous pouvez inclure des démonstrations interactives de votre code et organiser davantage votre documentation indépendamment de la structure du code..
La documentation CSS commence par des règles claires et une base de code bien structurée. Lorsque cela est fait dans le cadre de votre flux de travail, il peut également servir de guide pour structurer votre code et le garder organisé au fur et à mesure de sa croissance. Cela présente l’avantage supplémentaire de préciser clairement où et où un nouveau code devrait être ajouté, ce qui facilite l’intégration de nouveaux membres tout en accélérant le développement..
