Share
Quand il s’agit d’écrire du code, quel que soit le langage ou la plate-forme utilisée, nous, les développeurs, avons tendance à être divisés sur le point de savoir combien ou peu nous devrions commenter notre code..
D'un côté, certains pensent que le code devrait être auto-documenté. Autrement dit, il devrait être écrit suffisamment clair pour ne pas nécessiter de commentaires..
D'autre part, certains pensent que tout devrait être commenté. Autrement dit, il devrait y avoir des commentaires pour chaque classe, chaque fonction, chaque bloc et chaque ligne.
Ensuite, bien sûr, il y a ceux qui tombent au milieu. En fait, certains développeurs ne commentent que des zones de leur code qui peut être déroutant plutôt que de choisir l'approche du tout ou rien décrite ci-dessus.
Lorsqu'il s'agit d'écrire du code pour WordPress, nous avons les normes de codage WordPress qui fournissent une norme selon laquelle nous devrions écrire notre code; cependant, cela ne fournit pas de solides arguments pour ou contre les commentaires de code.
Dans cette série d'articles, je vais vous présenter un cas pour commentaires de code. Plus précisément, je vais expliquer en quoi ils sont importants, une recommandation sur la manière de le faire dans le contexte des fichiers standard requis de WordPress (pour les thèmes et les plugins), ainsi que pour la manière de le faire pour les fichiers HTML, les feuilles de style et JavaScript. des dossiers.
Avant d’examiner les différentes parties d’un projet WordPress, j’estime qu’il est important de discuter de l’importance même des commentaires de code. Bien sûr, la plupart d’entre nous savons qu’il s’agit de fournir une brève explication de ce qui se passe dans le code, mais les implications sont plus grandes que cela..
Malgré le fait que nous avons des normes selon lesquelles nous devrait écrivant notre code basé sur WordPress, certains développeurs les traitent comme des "recommandations", sans parler de ceux qui ne les connaissent même pas. Peu importe à quel point vous écrivez votre code, il est toujours code.
Après tout, si c'était facile à comprendre, cela ne s'appellerait pas du code (et nous n'aurions pas besoin de commentaires).
Je ne crois pas non plus que nous devrions écrire des commentaires de code en pensant uniquement aux autres. Je pense que nous devrions tout aussi bien les écrire pour nous-mêmes. Lorsque vous revisitez le code pour la première fois après un laps de temps important, il est fort probable que vous deveniez un meilleur programmeur, que vous ayez découvert quelques nouvelles techniques et / ou que vous aviez abandonné votre façon d'écrire du code. Ainsi, il peut être difficile de discerner ce que vous essayiez de faire.
Et s'il est difficile pour l'auteur du code à suivre, quel espoir y a-t-il pour les autres développeurs qui contribuent, développent ou améliorent le code?
En fin de compte, les commentaires doivent être adressés à nous-mêmes et aux autres personnes susceptibles d'interagir avec notre code. Ils doivent être clairs, concis et doivent fournir toutes les informations nécessaires qu'un développeur devrait connaître pour travailler avec la section de code donnée. Ceci inclut toute information faisant référence au code dans autre les fichiers (qu'ils soient côté serveur ou côté client), aussi.
Cela dit, j'aimerais aborder quelques raisons et stratégies pour commenter tous les fichiers qui entrent dans la création d'un thème, d'un plugin ou d'une application WordPress..
En fonction de votre projet, les fichiers que vous devez inclure varient. Pour les besoins de cet article, je suppose que vous incluez les fichiers PHP, les fichiers HTML, les feuilles de style et les fichiers JavaScript simplement pour vous assurer que toutes les bases sont couvertes. Dans cet article, nous allons parler du langage côté serveur, c'est-à-dire de PHP, et dans le prochain article, nous examinerons les langages côté client..
Quand il s’agit de commenter nos fichiers PHP, il y a plusieurs exigences à respecter:
Autre que cela, il y a vraiment très peu de commentaires requis, donc il y a évidemment matière à amélioration.
En ce qui concerne les commentaires de code en PHP, il existe en fait une méthode suggérée: PHPDoc. Semblable aux standards de codage WordPress, PHPDoc est un standard pour commenter (ou documenter) le code PHP. Il fournit un certain nombre de conventions qui s’appliquent toutes à WordPress, mais un sous-ensemble que je vois régulièrement utilisé.
WordPress prend en charge deux types de fichiers modèles:
Quand il s’agit de documenter des modèles de fichiers, quel que soit leur type, j’essaie toujours de fournir des informations d’en-tête qui définissent le nom du fichier, l’objet du fichier, le package - ou le thème ou le plugin - dont il fait partie, et depuis combien de temps il existe dans le projet.
Par exemple:
/ ** * Nom du modèle: Projets en vedette * * Le modèle utilisé pour la zone "Projets en vedette" de la page d'accueil. Parcourt le type d'article "Projets sélectionnés" et extrait les trois entrées les plus récentes. * * Thème du projet @package * @since 1.0 * /
Comme vous pouvez le voir, j'ai fourni le nécessaire Nom du modèle pour le fichier, mais j'ai également donné une courte description de ce qui se passe dans le fichier. J'ai aussi utilisé le @paquet et @puisque directives pour aider à donner plus de clarté.
le @paquet directive, du moins dans le contexte de WordPress, représente le nom du thème ou du plug-in dont ce fichier fait partie.
le @puisque directive représente depuis combien de temps le modèle existe dans le projet. Dans le cas ci-dessus, cela fait évidemment partie du projet depuis sa version initiale, mais il n'est pas du tout rare d'ajouter des fichiers alors qu'un thème ou un plugin mûrit, ce qui donne un numéro de version différent sous cette valeur..
En raison de la nature des fichiers de modèle de base tels que l'index, les modèles uniques, les modèles de page, d'archivage, etc., il n'est pas nécessaire de définir un "Nom du modèle,"mais la description, le package et les directives sont toujours pertinents.
La documentation des fonctions est très similaire à la documentation des modèles. Bien qu'ils ne nécessitent pas une balise spécifique - telle que "Nom du modèle"- ils doivent néanmoins inclure une description de l'objectif de la fonction et des @puisque directif.
Il existe également deux directives supplémentaires qu'une fonction peut éventuellement inclure:
Accentsconagua
@param qui décrit le type et la description d'un paramètre accepté par la fonction@revenir qui décrit le type et la description de ce que la fonction renvoieBien sûr, les fonctions n'acceptent pas toujours les paramètres et les fonctions ne renvoient pas toujours de valeurs, raison pour laquelle ces deux directives sont facultatives..
En supposant que votre fonction prenne en charge les deux directives ci-dessus, voici comment vous devez vous attendre à ce que la documentation apparaisse:
/ ** * Insère par programme une page dans la base de données. * * @param $ title Titre de la page. La variante minuscule sert également de slug de page. * @param $ nom_modèle Nom du fichier de modèle situé dans le répertoire 'modèles'. * @return L'ID de la page qui a été créée * @since 1.0 * /
Pour plus d'informations sur chacune de ces directives, vous pouvez consulter les balises PHPDoc; Cependant, vous pouvez voir à quel point cela peut être utile pour travailler sur un thème ou un plugin - cela vous évite beaucoup de devoir discerner ce que vous ou un autre développeur avez essayé d'accomplir avec une fonction donnée..
Bien qu'il existe peu de recommandations ou de normes pour la documentation de blocs de code, je pense toujours que cela est utile, en particulier lorsqu'il s'agit de boucles plus complexes ou conditionnelles..
Tout ceci peut être démontré dans l'exemple suivant: Supposons qu'il soit nécessaire de configurer une requête personnalisée pour effectuer une boucle dans les métadonnées post, puis de la supprimer si une clé et / ou une valeur donnée est trouvée. Cela nécessiterait les étapes suivantes:
Cet exemple documentera les lignes simples ainsi que les conditionnelles. Tout d’abord, jetons un coup d’œil au code source, puis nous verrons ce qu’il fait juste après:
// Configuration des arguments pour récupérer tous les articles publiés $ arguments = array ('post_type' => 'post', 'post_status' => 'publish', 'numberposts' => -1); // Instancie la requête $ posts_query = new WP_Query ($ arguments); // Si des publications sont trouvées, parcourez-les si ($ posts_query-> have_posts ()) while ($ posts_query-> have_posts ()) $ posts_query-> the_post (); / * * Pour chaque morceau de méta de post trouvé, stockez ses valeurs dans * les $ meta_key et $ meta_value à vérifier. * / foreach (get_post_meta (get_the_ID ()) sous la forme $ meta_key => $ meta_value) / * * Il peut y avoir plusieurs clés méta (telles que tweet_url_0, tweet_url_1) *, nous devons donc vérifier si le 'tweet_url' est situé dans la * $ meta_key. * * Si c'est le cas, nous pouvons supprimer les métadonnées post * / if (false! = Strstr ($ meta_key, 'tweet_url')) delete_post_meta (get_the_ID (), $ meta_key); // end if // end foreach // end while // end if // Réinitialisez la requête personnalisée pour ne pas interférer avec d'autres requêtes ou The Loop wp_reset_postdata (); Idéalement, les commentaires ci-dessus devraient fournir toute la documentation et les explications nécessaires pour comprendre ce qui se passe dans le code. Peut-être que la seule chose qui peut être nécessaire est la compréhension de la strstr une fonction.
Le point clé que j’essaie de souligner avec le code ci-dessus est que si nous documentons des lignes uniques, il est préférable de s’en tenir à la convention de ligne unique - c’est-à-dire que // - mais si nous écrivons un commentaire qui s'étend sur plusieurs lignes, il est toujours préférable d'utiliser le commentaire multiligne - c'est-à-dire, / * * /.
Notez également que toutes les lignes ne sont pas a être commenté. Plutôt, des blocs (ou des morceaux) de code peuvent être expliqués dans un commentaire multiligne qui documente ce qui va se passer dans le code source suivant.
Bien sûr, ce n’est pas une manière standard ni une façon préférée de faire les choses. C'est simplement une stratégie que j'ai vue utilisée, que j'apprécie et que je m'utilise moi-même.
Si vous vous conformez aux conventions énoncées dans PHPDoc, de nombreux utilitaires peuvent générer des pages de documentation pour votre travail. On peut dire que l'outil le plus populaire est phpDocumentor.
En bref, phpDocumentor est un utilitaire qui va parcourir votre code source à la recherche de commentaires de code PHPDoc correctement formatés (en particulier sur les classes et les fonctions), puis générer un ensemble de pages stylisées capturant les informations dans vos commentaires.
Cela rend la documentation orientée développeur avec votre application plus facile à expédier.
Tout au long de cet article, j'ai expliqué pourquoi, à mon avis, les commentaires de code devraient figurer dans tous les développeurs. Bien que le codex WordPress définisse un ensemble de commentaires de base nécessaires à notre travail et / ou à l’interface avec l’application WordPress, il est évident que nous pouvons faire davantage pour améliorer la clarté de notre code..
Le fait est que nous n'en avons couvert que la moitié. Ainsi, dans le prochain article, nous examinerons la documentation du balisage, du JavaScript et des styles..
@paquet Directif@puisque Directifstrstr