Quelle est la qualité de vos commentaires HTML et CSS?

L'une des choses que vous apprenez habituellement lorsque vous commencez à apprendre sur HTML ou CSS de base est de savoir comment écrire des commentaires dans votre code. Cependant, de nombreux développeurs Web n'utilisent toujours pas de commentaires à leur avantage. Nous pouvons utiliser des commentaires largement dans HTML et CSS, mais lorsqu'ils sont écrits correctement, et avec l'intention, ils peuvent vraiment améliorer notre flux de travail.

Lorsque vous commencez à travailler dans une nouvelle entreprise, regarder des manuels ou de nombreuses pages de documentation peut être intimidant. Chaque entreprise est différente - ce qui signifie que les bases de code, la quantité de code hérité, le développement de cadres et la quantité de code modulaire peuvent être différents.

On nous dit souvent que "le bon code n'a pas besoin de commentaires", mais vous êtes-vous déjà retrouvé en rond, complètement perdu et recherchant de la documentation à cause d'un manque de commentaires?

Les plats clés

• Les commentaires sur HTML et CSS facilitent non seulement la compréhension et la cohérence, mais accélère également le processus de développement et facilite une collaboration efficace. Il est particulièrement utile dans une équipe où plusieurs développeurs travaillent sur le même projet.
• Bien que les commentaires soient bénéfiques, évitez en faire trop. Commentant chaque bloc de code peut être redondant et long. Les commentaires doivent être concis et utilisés uniquement lorsque le code peut ne pas être complètement clair.
• Les commentaires peuvent être utilisés pour expliquer le but d'un pseudo, un bloc de code imbriqué, pourquoi!
D'autres formes de documentation, telles que les messages de validation et les demandes de traction, doivent également être considérées comme faisant partie du processus de développement. Ils fournissent le contexte et la clarté, rendant la collaboration et l'examen du code plus efficaces.

Deux faits sur les commentaires du code

Les commentaires sont ignorés par le navigateur.
Les commentaires sont supprimés pendant la minification.

Sur la base de ces deux faits, nous savons que les commentaires ne sont pas vraiment destinés aux machines - ils sont destinés à

pour que les humains lisent .

Pourquoi le code de commentaire est important

lorsque vous travaillez et travaillez sur un projet solo, ou lorsque vous êtes le seul développeur à regarder votre code, il est facile de vous procéder à votre propre chemin et de faire des commentaires comme bon, ou peut-être ne laissez aucun commentaire du tout. Mais la plupart du temps, les développeurs disent qu'ils regardent leur propre code et se demandent: «À quoi je pensais?» ou lutter pour comprendre ce code qu'ils ont écrit.

Les commentaires peuvent aider à maintenir la cohérence. Si vous avez des commentaires cohérents et bien écrits pour ce que vous construisez, vous êtes plus susceptible de construire les choses de la même manière à chaque fois.

Les commentaires facilitent la compréhension. Ceci est vraiment important dans une équipe où parfois une personne ne fait pas tout le travail. Vous pouvez écrire des commentaires pour vous aider à comprendre une logique, et même si vous ne gardez pas tous vos commentaires à la fin du projet, cela peut vous aider à mieux comprendre comment vous êtes arrivé à une solution. Il peut vous aider à améliorer cette solution beaucoup plus facilement plus tard.

Les commentaires peuvent également aider avec des filettes à chaud ou des corrections rapides. Les commentaires peuvent en fait aider de trois manières ici. Ils peuvent aider les développeurs à comprendre le code s'ils ont besoin de faire une solution rapide (en particulier les développeurs en dehors de l'équipe frontale qui peuvent aider), il peut aider en marquant où ces correctifs sont nécessaires et peuvent montrer où des correctifs rapides ont été appliqués et doivent être supprimés à un moment donné.

Les commentaires aident à accélérer le processus de développement. Vous pouvez avoir une compréhension plus claire de ce que vous créez, changez ou supprime si vous incluez les commentaires pertinents.

Les commentaires facilitent une collaboration plus efficace. Si vous connaissez les tenants et aboutissants d'un projet ou d'une base de code, vous êtes plus susceptible de faire des bits et des pièces plus rapidement, améliorant ainsi les flux de travail.

Les commentaires aident beaucoup de gens. Ils vous aident non seulement, mais ils peuvent aider d'autres personnes de votre équipe. Il est révolu le temps où nous avons vu des commentaires comme ne pas voler mon code dans le code source des gens. Bien que nous soyons très protecteurs de notre code, ne voulant pas partager nos «secrets», nous vivons maintenant dans un monde où les gens partagent le code, travaillons sur des projets ensemble et collaborons. Nous n'avons pas honte de créditer Harry Roberts, Chris Coyier ou Jonathan Snook en ce qui concerne les projets Web. Avec ce changement de collaboration, nous devons également prendre note de nos pratiques de commentaires - et aider nos pairs.

certaines choses à éviter en ce qui concerne les commentaires

Évitez de commenter absolument tout

Il peut être tentant de prendre l'habitude de commenter chaque bloc de code, mais cela peut être plus redondant que utile ou utile. Les commentaires ne doivent être faits que lorsque quelque chose peut ne pas être complètement clair. Si vous avez envisagé la sémantique lors de la dénomination de vos cours, votre code peut déjà être facile à comprendre.

Cela peut également être d'où le concept de «bon code n'a pas besoin de commentaires». Les commentaires ne doivent pas être complètement évités, mais utilisés uniquement si nécessaire.

Ne soyez pas trop verbeux

Je suis personnellement coupable d'écrire des commentaires assez longs dans mon CSS, parce que j'aime expliquer et documenter les choses. Cependant, vous ne devriez pas écrire de romans - les longs commentaires sont autant pénibles à lire que possible. Si vous pouvez être succinct, faites-le. Parfois, lors de la dénomination des classes CSS, les conseils suivants sont donnés:

rendre les noms de classe aussi courts que possible mais aussi longtemps que nécessaire.

La même chose s'applique aux commentaires. Il est bon de lire tous les commentaires que vous écrivez pour vous assurer de les comprendre vous-même. Imaginez que vous êtes quelqu'un de nouveau dans le code et que vous lisez les commentaires comme un guide.

Ne passez pas trop de temps à écrire des commentaires

J'ai vu une fois un fichier dans un projet sur lequel je travaillais qui avait une ligne à la lecture supérieure:

<span>// Update this with how many hours you have spent on this file:
</span><span>// TIME_WASTED = 438;</span>

Vous ne devriez pas avoir besoin de passer beaucoup de temps à écrire des commentaires. Quelques mots suffisent généralement. Si vous passez trop de temps à essayer de commenter votre code pour vous assurer que quelqu'un d'autre le comprendra, considérez que les parties de votre code pourraient réellement avoir besoin de refactorisation.

quelques exemples de quand utiliser les commentaires

pour expliquer le but d'un élément pseudo

Cet exemple montre un pseudo avec la valeur de contenu remplie.

<span><span>.post__comment-container::after</span> {
</span>  <span>background-color: #f9f9f9;
</span>  <span>border: 1px solid #dedede;
</span>  <span>border-radius: 0.25em;
</span>  <span>color: #888;
</span>  <span>content: 'Post author';
</span>  <span>display: inline-block;
</span>  <span>font-size: 0.7rem;
</span>  <span>margin-left: 0.5rem;
</span>  <span>padding: 0.2rem 0.45rem;
</span>  <span>vertical-align: middle;
</span><span>}</span>

Il peut ne pas être immédiatement clair à quoi sert un pseudo, surtout si la propriété de contenu est affichée en tant que contenu: ''. Avec un court commentaire au-dessus du bloc de code, nous pouvons améliorer cela.

/* Post author label for comment */

<span><span>.post__comment-container::after</span> {
</span>  <span>background-color: #f9f9f9;
</span>  <span>border: 1px solid #dedede;
</span>  <span>border-radius: 0.25em;
</span>  <span>color: #888;
</span>  <span>content: 'Post author';
</span>  <span>display: inline-block;
</span>  <span>font-size: 0.7rem;
</span>  <span>margin-left: 0.5rem;
</span>  <span>padding: 0.2rem 0.45rem;
</span>  <span>vertical-align: middle;
</span><span>}</span>

pour expliquer un bloc de code imbriqué

Bien qu'il aide certainement à utiliser autant que possible les classes sémantiques, il peut ne pas toujours être clair pourquoi un bloc de CSS serait imbriqué lors de l'utilisation d'un préprocesseur:

<span><span>.c-segment-controls.is-active</span> {
</span>  <span><span>.c-segment-controls__panel</span> {
</span>    <span>background-color: #fafafa;
</span>    <span>border: 1px solid #aaa;
</span>    <span>opacity: 1;
</span>    <span>transition: opacity 0.5s ease;
</span>  <span>}
</span><span>}</span>

six mots suffisent pour qu'un commentaire indique ce que fait ce bloc de code, permettant à quelqu'un de pouvoir parcourir le document et s'arrêter ou sauter.

<span><span>.c-segment-controls.is-active</span> {
</span>
  <span>/* Active state for segment controls panel */
</span>
  <span><span>.c-segment-controls__panel</span> {
</span>    <span>background-color: #fafafa;
</span>    <span>border: 1px solid #aaa;
</span>    <span>opacity: 1;
</span>    <span>transition: opacity 0.5s ease;
</span>  <span>}
</span><span>}</span>

pour expliquer pourquoi!

Nous voyons souvent! IMPORTANT et supposons que nous regardons le code hérité ou un hack sale:

<span><span>.c-accordion-container.ng-hide</span> {
</span>  <span>display: block !important;
</span><span>}</span>

En y regardant une inspection plus approfondie, nous ne faisons que remplacer le comportement par défaut d'un framework.

/**
 * Overriding some rogue Angular code.
 * Forces `display: block` so that the element can be animated.
 */

<span><span>.c-accordion-container.ng-hide</span> {
</span>  <span>display: block !important;
</span><span>}</span>

pour expliquer pourquoi un bloc de code a été commenté plutôt que simplement supprimé

Si nous regardons le bloc de code ci-dessous, nous pouvons supposer que la suppression est bien. Il n'est sûrement pas utilisé nulle part? Si je le supprime, il sera de toute façon dans le contrôle de version lorsque nous en aurons besoin plus tard, non?

<span>// .c-segmented-button__icon {
</span><span>//   transform: translateY(calc((40px - 100%)/2));
</span><span>// }</span>

Mais si nous le supprimons, quelqu'un pourrait même ne pas savoir qu'il existait en premier lieu. Ce pourrait être une bonne idée de laisser ceci ici:

/**
 * Calculation for vertical alignment.
 * Can be used when IE11 support is dropped.
 */

<span>// .c-segmented-button__icon {
</span><span>//   transform: translateY(calc((40px - 100%)/2));
</span><span>// }</span>

Autres types de documentation

La documentation est vraiment importante et ne se limite pas aux commentaires dans le code. Lorsque nous avons terminé avec une tâche, nous pourrions le faire évaluer par des pairs.

commettre des messages

Lorsque vous utilisez le contrôle de version (par exemple, GIT), nous pouvons prendre ce que nous savons sur la rédaction de commentaires utiles dans le code et l'appliquer à nos messages de validation.

Les messages de mauvais engagement ne donnent pas beaucoup de contexte. Ils ont l'air bâclés et peuvent être difficiles à comprendre. Ils ne sont pas utiles pour les notes de sortie. Il peut être difficile pour un développeur de savoir ce qui a changé. Les mauvais messages de validation ressemblent souvent à ceci.

commit 2faa2
    wip
commit 591ad
    tried to fix some weird box
commit af830
    made the triangle thing work
commit bd02a
    refactor
commit bed4b
    hotfix navigation
commit 22fe0
    oops

Un meilleur exemple décrirait, en utilisant un verbe, la tâche terminée dans un engagement. Différentes tâches mineures seraient réparties sur différents engins.

<span>// Update this with how many hours you have spent on this file:
</span><span>// TIME_WASTED = 438;</span>

Karma a un guide assez simple pour écrire de meilleurs engagements, tandis que Chris Beams a un guide très approfondi. David DeMaree a même écrit un article intitulé «L'art de la commission». Les messages de validation méritent certainement une certaine attention.

Pull Demandes

Après avoir écrit une poignée de commits, vous créez généralement une demande de traction pour que l'un de vos pairs puisse regarder. J'ai vu une de trop de demandes de traction qui ont très peu de détails ou pas de description du tout:

Lorsque vous écrivez une demande de traction, vous vous attendez généralement à ce que quelqu'un examine votre code. Pour aider cette personne et aider à soulager le processus, vous devez écrire une description de ce que la demande de traction comprend. Ceci est ma liste de contrôle mental:

• numéro de billette, numéro de tâche ou numéro de problème
• Mentionnez la tâche en quelques mots
• mentionner les types de fichiers que j'ai changés
• Si c'était un bug, mentionnez à quoi ressemblait le bug avant et après les modifications
• Décrire le comportement attendu après les changements (devrait-il être le même?)
• Énumérez toutes les étapes qui doivent être prises pour vérifier les modifications, soit dans le navigateur ou dans le code
• Notez tout ce qui doit être ignoré, par exemple un bug adressé dans une autre branche
• Inclure des captures d'écran de l'interface si nécessaire

Cet exemple est relativement simple, et vous n'avez certainement pas à inclure tout dans la liste ci-dessus si elle n'est pas nécessaire:

Conclusion

Bien que j'ai fourni quelques exemples de savoir où inclure des commentaires et quelques suggestions sur ce qu'il faut éviter, il n'y a pas de règles strictes sur la façon de formater les commentaires dans votre code. Le nombre de lignes, de mots ou quelles informations inclure vous appartiennent, ou peuvent être décidées entre vous et vos pairs. Tant que vous gardez le format cohérent, il gardera les choses bien rangées et encouragera les autres qui travaillent avec le code pour faire de même.

Il y a de nombreux avantages associés à faire des commentaires une partie de votre processus de développement. Il est bon de prendre l'habitude de les inclure là où vous en jugez, surtout lorsque vous avez beaucoup de gens qui travaillent sur les mêmes fichiers. Il aide également à considérer d'autres formes de documentation qui sont intégrées dans les workflows - telles que les messages de validation et les demandes de traction - et pas simplement un document externe des directives.

Suivez-vous des directives pour commentaire du code? Ou peut-être que vous travaillez dans une entreprise qui a un type de documentation différent mais efficace?

Questions fréquemment posées (FAQ) sur les commentaires HTML et CSS

Quelle est l'importance d'utiliser des commentaires dans HTML et CSS?

Les commentaires dans HTML et CSS sont cruciaux pour plusieurs raisons. Premièrement, ils aident à comprendre la structure et la fonctionnalité du code, en particulier lorsqu'ils travaillent dans une équipe ou revisitent votre code après une longue période. Deuxièmement, ils peuvent être utilisés pour désactiver temporairement certaines parties de votre code pendant le débogage. Enfin, les commentaires peuvent fournir des informations ou des instructions utiles à toute personne lisant le code.

Comment puis-je commenter le code dans HTML et CSS?

En HTML, vous pouvez commenter le code en l'enroulant entre . Par exemple, . Dans CSS, les commentaires sont faits en enroulant le texte entre / * et /. Par exemple, / Il s'agit d'un commentaire * /.

Les commentaires peuvent-ils affecter les performances de mon site Web?

Non, les commentaires n'affectent pas les performances de votre site Web. Ils sont ignorés par le navigateur pendant le processus de rendu. Cependant, les commentaires excessifs peuvent augmenter la taille du fichier, ce qui peut légèrement affecter le temps de chargement.

Quelles sont les meilleures pratiques pour écrire des commentaires dans HTML et CSS?

Certaines meilleures pratiques pour écrire des commentaires incluent Être concis mais descriptif, commentant des sections complexes ou importantes de code et éviter les commentaires inutiles ou redondants. Il est également une bonne pratique de mettre à jour régulièrement vos commentaires pour refléter les modifications de votre code.

Puis-je utiliser des commentaires pour masquer le code à certains navigateurs?

Oui, les commentaires peuvent être utilisés pour masquer le code de certains navigateurs. Cette technique, connue sous le nom de commentaires conditionnelles, est souvent utilisée pour fournir différents styles ou scripts pour différentes versions d'Internet Explorer.

Comment puis-je utiliser des commentaires pour le débogage?

Les commentaires peuvent être utilisés pour le débogage en désactivant temporairement certaines parties de votre code. Cela peut vous aider à isoler et à identifier les sections problématiques de votre code.

Puis-je nidifier les commentaires dans HTML et CSS?

En HTML, vous ne pouvez pas nicher de commentaires. Tenter de le faire peut entraîner des résultats inattendus. Dans CSS, vous pouvez nicher les commentaires, mais il n'est généralement pas recommandé car il peut rendre votre code plus difficile à lire et à comprendre.

Quelle est la différence entre les commentaires unique et multi-lignes?

Les commentaires en une seule ligne sont utilisés pour de courtes explications ou annotations, tandis que les commentaires multi-lignes sont utilisés pour des descriptions plus longues ou des blocs de code. Dans HTML, tous les commentaires sont techniquement multi-lignes. Dans CSS, les commentaires en une seule ligne commencent par // et se terminent à la fin de la ligne, tandis que les commentaires multi-lignes commencent par / * et se terminent par * /.

Puis-je utiliser des caractères spéciaux dans mes commentaires?

Oui, vous pouvez utiliser des caractères spéciaux dans vos commentaires. Cependant, dans HTML, vous devez éviter d'utiliser les personnages «-» dans vos commentaires car ils peuvent entraîner la fin du commentaire prématurément.

Comment puis-je utiliser des commentaires pour améliorer la lisibilité de mon code?

Les commentaires peuvent améliorer la lisibilité de votre code en fournissant des explications et des annotations. Ils peuvent également être utilisés pour séparer les différentes sections de votre code, ce qui facilite la navigation. Cependant, il est important de trouver un équilibre entre les commentaires et la surcoumination. Trop de commentaires peuvent rendre votre code encombré et plus difficile à lire.

Ce qui précède est le contenu détaillé de. pour plus d'informations, suivez d'autres articles connexes sur le site Web de PHP en chinois!