Share
Dans cette série en deux parties, nous examinons la possibilité de générer des arguments pour les commentaires de code. Dans le premier article, nous avons couvert le côté serveur en jetant un coup d'œil à PHP. Plus précisément, nous avons examiné les conventions PHPDoc et leur utilisation pour documenter des modèles, des fonctions, des lignes et des blocs..
Dans cet article, nous allons examiner les langages côté client. Plus précisément, nous allons examiner HTML, CSS et JavaScript.
Bien qu'il n'y ait pas nécessairement d'utilitaires de documentation tels que phpDocumentor pour toutes ces langues, il existe toujours des stratégies que nous pouvons employer pour faciliter la maintenance de nos projets (ou aider les autres à contribuer à nos projets).
Pour ce qui est de travailler avec WordPress, les types de fichiers qu’ils contiennent varient en fonction des thèmes et des plug-ins. Les thèmes se composent généralement de HTML et de CSS et probablement de JavaScript, alors que les plugins peut composé uniquement de PHP.
Dans le premier article, nous avons examiné les besoins de WordPress pour l’enregistrement de modèles de fichiers avec l’API, ainsi que sur les plug-ins nécessaires. Avant de lire à l'avance, je recommande de lire d'abord cet article car il couvre les informations requises, alors que cet article en particulier ne couvrira que les recommandations sur ce que nous pouvons faire pour améliorer nos commentaires..
La plupart des développeurs Web savent comment écrire des commentaires dans le contexte du HTML. Simplement, il suffit de préfixer le code - qu’il s’agisse d’une simple ligne ou d’un bloc - avec . Quand il s’agit d’écrire du balisage, il n’est pas très courant de voir des commentaires au-delà des conditionnelles que vous pouvez trouver dans le tête élément du document.
Il existe des techniques que nous pouvons utiliser pour rendre notre code plus facile à gérer. Ceci est particulièrement utile lorsque vous travaillez avec des systèmes tels que WordPress, car certains éléments seront répartis sur plusieurs fichiers..
Par exemple, en supposant que vous construisiez un thème, vous allez probablement ouvrir votre corps élément et un élément de conteneur dans le header.php modèle, puis en terminant les éléments dans le footer.php modèle.
Ceci est un exemple un peu simplifié car relativement commun, mais le principe reste le même dans les autres fichiers..
Cela dit, il existe une stratégie simple que nous pouvons utiliser pour commenter notre code:
Les éléments HTML seront généralement sous l'une des quatre formes suivantes:
Pour chacune de ces permutations, je suis les conventions suivantes:
Ci-dessus, un extrait de code pour un formulaire est utilisé pour enregistrer des options dans le formulaire de base de données WordPress dans le tableau de bord. Dans ce cas, je laisserai normalement un commentaire à la fin de l'élément indiquant l'objectif du formulaire ou un autre attribut, tel que l'attribut action..
Compte tenu de cette stratégie, l'exemple ci-dessus peut ressembler à ceci:
Ou:
La convention que j'utilise est d'utiliser une barre oblique inverse - en mode HTML normal - suivie du but de la description de l'élément pour me laisser savoir que je termine l'élément..
Bien que cela puisse ne pas être particulièrement utile avec un seul élément isolé, je l'ai trouvé utile pour les éléments imbriqués ainsi que lorsqu'un élément - comme un conteneur - est divisé en fichiers..
Dans le cas où l'élément a un identifiant, j'utilise le commentaire suivant:
Comme ci-dessus, j'utilise une barre oblique inverse suivie d'un "#'qui représente un identifiant en CSS suivi du nom de la valeur de l'attribut ID. Cela me permet de savoir que je termine un élément avec l'identifiant donné.
Encore une fois, ceci est plus utile lorsqu'un élément existe dans plusieurs fichiers, mais aussi lorsque vous devez effectuer une recherche globale dans des fichiers de modèle ou dans des fichiers CSS..
Lorsqu'un élément n'inclut qu'une classe (ou un ensemble de classes), je suis une stratégie similaire à celle décrite ci-dessus: j'utilise une barre oblique inversée, l'indicateur CSS d'une classe, puis la classe (ou la première classe) de l'élément:
Assez simple.
Mais que se passe-t-il lorsque l'élément comprend à la fois un identifiant et une classe? Étant donné que les identifiants sont uniques et que les noms de classe ne le sont pas, par défaut, j'utilise toujours l'identifiant de l'élément pour mettre fin au commentaire:
C'est logique, non? Et le point demeure: cela permet de savoir facilement quel élément je termine et de le trouver facilement dans le reste des fichiers de projet..
JavaScript est similaire à PHP en ce sens qu'il prend en charge des fonctionnalités d'ordre supérieur telles que des fonctions (et des prototypes si vous écrivez du code JavaScript à la vanille). Pour cette raison, il est utile de disposer d'une convention par laquelle nous documentons nos fonctions..
En voici le principe: WordPress inclut jQuery par défaut. Il est donc courant que la plupart des scripts JavaScript spécifiques à WordPress soient écrits à l'aide d'une combinaison de JavaScript basé sur jQuery et de fonctionnalités telles que vanilla..
Les stratégies suivantes se sont révélées utiles pour écrire du code JavaScript dans WordPress:
Tout d’abord, j’essaie de nommer le fichier en fonction de son objectif (tel que navigation.js ou theme.js ou admin.js).
Deuxièmement, je fournirai également une brève description en haut de chaque fichier en utilisant les conventions PHPDoc pour décrire le fichier et la durée depuis laquelle il fait partie du projet:
/ ** * admin.options.js * * Gère les gestionnaires d'événements de plusieurs éléments sur la page d'options du tableau de bord. * * @since 1.0 * @version 3.2 * /
Pour les fonctions, je suis une convention similaire à celle décrite ci-dessus, dans laquelle je vais décrire brièvement la fonction, décrire ce qu’elle accepte et ce qu’elle renvoie, ainsi que la durée depuis le projet et la version actuelle du fichier:
/ ** * Fonction d'assistance déclenchée lorsque l'utilisateur clique sur 'Terminé' ou appuie sur 'Entrée' * lorsqu'il s'emploie à enregistrer ses icônes de réseaux sociaux. * * @param $ Une référence à la fonction jQuery * @param evt L'événement source de ce gestionnaire * @returns Indique si l'utilisateur doit entrer ou annuler la saisie pour enregistrer ses options. * @since 1.0 * @version 1.2 * /
Ce n'est vraiment rien de plus que des commentaires de code standard que la plupart des développeurs utilisent souvent. Il y a la variation à une seule ligne, la variation multiligne et le but qu'elles servent: il s'agit simplement de décrire ce qui est sur le point de se passer dans le code après le commentaire.
Accentsconagua
/ * * Si nous examinons l'icône du flux RSS, désactivez l'entrée * et associez l'utilisateur aux options globales pour définir où. * / if ("! == sRssUrl) $ ('# social-icon-url') .val (sRssUrl) .attr ('disabled', 'disabled'); else $ ('# social-icon- url '). removeAttr (' disabled '); // end if Il y a très peu de choses à ajouter à cela que je n'ai pas abordées dans le premier article, mais je voulais le mentionner ici pour être examiné et être complet..
Bien qu'il n'y ait pas d'outil de documentation JavaScript officiel, jsDoc est devenu l'un des utilitaires les plus courants pour la documentation du code JavaScript..
Il est décidément beaucoup plus facile de commenter des fichiers CSS que de travailler avec PHP ou avec des balises, car il n’existe en réalité qu’une seule façon d’écrire des styles..
C'est-à-dire que vous définissez les styles d'un élément à l'aide d'un ID ou d'une classe:
# no-comments font-size: 24px; hauteur de ligne: 36px; poids de police: gras; couleur: # 444;
Ou:
.home .sticky: before display: inline-block; fond: url transparente (images / sticky.png) non répétée; largeur: 58px; hauteur: 45px; contenu: ""; position: absolue; en haut: 26px; à gauche: -9px;
De manière générale, je ne pense pas que vous ayez besoin de commenter les styles, mais si vous vous trouvez dans une situation où la parenthèse terminale est en dehors de l'écran, il peut être utile de terminer le style avec un commentaire comme celui-ci:
# no-comments font-size: 24px; hauteur de ligne: 36px; poids de police: gras; couleur: # 444; /* #Sans commentaires */
Ou:
.home .sticky: before display: inline-block; fond: url transparente (images / sticky.png) non répétée; largeur: 58px; hauteur: 45px; contenu: ""; position: absolue; en haut: 26px; à gauche: -9px; / * .home .sticky: avant * /
À l'heure actuelle, l'utilisation de langages tels que LESS et Sass et leurs préprocesseurs respectifs devient de plus en plus populaire dans le développement Web. L’une des caractéristiques les plus communes de ces deux langues est qu’elles supportent les règles imbriquées..
Dans ce cas, je pense qu'il est beaucoup plus justifié d'utiliser des commentaires. Par exemple:
#header #slideshow # image-list list-style: none; float: gauche; marge: 0; largeur: 100%; // # liste-images // #slideshow // #header
De cette façon, vous savez quel élément vous terminez quel que soit le début de l'élément dans l'EDI.
Tout au long de cette série, j'ai expliqué pourquoi, selon moi, les commentaires de code devraient figurer dans tous les développeurs. Dans cet article, j'ai présenté mes stratégies pour commenter mon balisage, mon JavaScript et mes styles..
Bien que je ne dis pas mon chemin est le seulement Une façon d'écrire des commentaires - ce n'est qu'un moyen - je pense que l'inclusion de commentaires contribue grandement à rendre un projet plus facile à gérer pour vous et vos pairs, et je pense que chaque développeur doit viser leur inclusion dans votre travail..
Espérons que cette série a fourni un cas pour cela. Quoi qu'il en soit, j'aimerais entendre vos commentaires et suggestions dans les commentaires..
