Code source Commentaire Conseils de style et bonnes pratiques

Les développeurs qui ont passé du temps sur de grands projets comprennent l’importance des commentaires de code. Lorsque vous intégrez de nombreuses fonctionnalités dans la même application, les choses se compliquent. Il y a tellement de bits de données, y compris des fonctions, des références de variables, des valeurs de retour, des paramètres… comment vous attendez-vous à les suivre??

Il n’est donc pas surprenant que le commentaire de votre code soit essentiel, tant pour les projets en solo que pour les projets d’équipe. Mais beaucoup de développeurs ne savent pas comment s'y prendre. J'ai présenté certaines de mes astuces personnelles pour créer des commentaires de code formatés et ordonnés. Les normes et les modèles de commentaires varient d’un développeur à l’autre, mais vous devez au final vous efforcer commentaires propres et lisibles pour expliquer davantage les zones confuses dans votre code.

Nous devrions commencer à discuter de certaines des différences de formatage des commentaires. Cela vous donnera une meilleure idée de la précision avec laquelle vous pouvez devenir avec le code de projet. Ensuite, je vous proposerai des conseils et des exemples spécifiques que vous pourrez commencer à utiliser immédiatement.!

Styles de commentaire: un aperçu

Il convient de noter que ces idées présentées ne sont que des lignes directrices vers des commentaires plus propres. Les langages de programmation individuels ne définissent pas de directives ni de spécifications pour la configuration de votre documentation..

Cela étant dit, les développeurs modernes se sont regroupés pour formater leur propre système de commentaire de code. Je vais offrir quelques styles traditionnels et entrer dans les détails de leur but.

Commentaires en ligne

Pratiquement chaque langage de programmation offre commentaires en ligne. Celles-ci sont limitées au contenu d'une seule ligne et ne commentent le texte qu'après un certain point. Ainsi, par exemple, en C / C ++, vous commencez un commentaire intégré comme ceci:

// commence la liste des variables var myvar = 1;… 

C'est parfait pour entrer quelques secondes dans le code. expliquer des fonctionnalités potentiellement déroutantes. Si vous travaillez avec beaucoup de paramètres ou d'appels de fonction, vous pouvez placer une multitude de commentaires en ligne à proximité. Mais l'utilisation la plus bénéfique est un explication simple pour une petite fonctionnalité.

if (callAjax ($ params)) // a exécuté callAjax avec succès avec les paramètres utilisateur… code

Remarquez surtout que le code devrait être sur une nouvelle ligne après le crochet d’ouverture. Sinon, tout serait pris sur la même ligne de commentaire! Évitez d'aller à la mer étant donné que vous n'avez généralement pas besoin de voir des commentaires d'une seule ligne tout au long de votre page, mais en particulier en cas de confusion dans les jonctions de votre code, il est beaucoup plus facile de les déposer à la dernière minute..

Blocs descriptifs

Lorsque vous devez inclure une explication volumineuse, une seule doublure ne suffit généralement pas. Des modèles de commentaires pré-formatés sont utilisés dans presque tous les domaines de la programmation.. Blocs descriptifs sont particulièrement visibles autour des fonctions et des fichiers de bibliothèque. Lorsque vous configurez une nouvelle fonction, il est recommandé de ajouter un bloc descriptif au-dessus de la déclaration.

/ ** * @desc ouvre une fenêtre modale pour afficher un message * @param string $ msg - le message à afficher * @return bool - succès ou échec * / function modalPopup ($ msg) … 

Ci-dessus, un exemple simple de commentaire de fonction descriptive. J'ai écrit une fonction vraisemblablement en JavaScript appelée modalPopup qui prend un seul paramètre. Dans les commentaires ci-dessus, j'ai utilisé une syntaxe similaire à phpDocumentor, où chaque ligne est précédée d'un @ symbole suivi d'une touche sélectionnée. Celles-ci ne vont en aucun cas affecter votre code, vous pouvez donc écrire @la description au lieu de @desc sans aucun changement.

Ces petites clés sont en fait appelées balises de commentaire qui sont largement documentés sur le site. N'hésitez pas à créer le vôtre et à les utiliser comme bon vous semble dans votre code. Je trouve qu'ils aident à garder tout ce qui coule afin Je peux vérifier des informations importantes en un coup d'œil. Vous devriez également remarquer que j'ai utilisé le / * * / format de commentaire en bloc. Cela gardera tout beaucoup plus propre que d'ajouter une double barre oblique commençant à chaque ligne.

Commentaires de groupe / classe

En plus de commenter les fonctions et les boucles, les zones de bloc ne sont pas utilisées aussi fréquemment. Où vous avez vraiment besoin de fort bloquer les commentaires sont à la tête de vos documents backend ou de vos fichiers de bibliothèque. Il est facile de tout mettre en œuvre pour rédiger une documentation solide pour chaque fichier de votre site Web. Cette pratique est visible dans de nombreux systèmes de gestion de contenu tels que WordPress..

La partie supérieure de votre page doit contenir des commentaires sur le fichier lui-même. De cette façon, vous pouvez vérifier rapidement où vous éditez lorsque vous travaillez sur plusieurs pages en même temps. De plus, vous pouvez utiliser cette zone comme une base de données pour les fonctions les plus importantes dont vous aurez besoin hors de la classe.

/ ** * @desc cette classe contiendra des fonctions pour l'interaction utilisateur * les exemples incluent user_pass (), user_username (), user_age (), user_regdate () * @author Jake Rocheleau [email protected] * @ requis settings.php * / classe abstraite myWebClass  

Vous pouvez voir que j'ai utilisé juste une petite classe d'échantillon pour le faux myWebClass code. J'ai ajouté des méta-informations avec mon nom et adresse e-mail pour le contact. Lorsque les développeurs écrivent du code source ouvert, il s’agit généralement d’une bonne pratique, de sorte que d’autres peuvent vous contacter pour obtenir de l’aide. C'est également une méthode solide lorsque vous travaillez dans des équipes de développement plus importantes..

Le tag @Champs obligatoires ce n'est pas quelque chose que j'ai vu utilisé ailleurs. J'ai suivi le format dans quelques-uns de mes projets, mais uniquement dans les pages sur lesquelles j'ai personnalisé de nombreuses méthodes. Chaque fois que vous incluez des pages dans un fichier, celles-ci doivent précéder la sortie du code. Donc, ajouter ces détails dans le bloc de commentaires de la classe principale est un bon moyen de rappelez-vous quels fichiers sont nécessaires.

Commentaire de code frontal

Maintenant que nous avons couvert 3 modèles de commentaires importants, examinons quelques autres exemples. De nombreux développeurs front-end sont passés du code HTML statique au code jQuery et CSS. Les commentaires HTML ne sont pas aussi utiles par rapport aux applications de programmation, mais lorsque vous écrivez des bibliothèques de styles et des scripts de page, les choses peuvent devenir compliquées avec le temps..

JavaScript suit une méthode de commentaire plus traditionnelle similaire à Java, PHP et C / C.++. CSS utilise uniquement les commentaires de style bloc délimités par une barre oblique et un astérisque. N'oubliez pas que les commentaires seront ouvertement affichés pour vos visiteurs, puisque ni CSS ni JS ne sont analysés côté serveur, mais que l'une ou l'autre de ces méthodes fonctionne parfaitement pour laisser des informations utiles dans votre code..

Casser des fichiers CSS peut être une corvée. Nous savons tous comment laisser un commentaire en ligne pour expliquer un correctif pour Internet Explorer ou Safari. Mais je pense que les commentaires CSS peuvent être utilisés au niveau de jQuery et que PHP les utilise. Explorons la création de groupes de styles avant d'aborder quelques astuces détaillées sur les commentaires de code..

Groupes de styles CSS

Pour ceux qui conçoivent le CSS depuis des années, il s'agit presque d'une seconde nature. Vous mémorisez lentement toutes les propriétés, la syntaxe et construisez votre propre système pour les feuilles de style. À travers mon propre travail, j'ai créé ce que j'appelle regroupement coupler des blocs CSS similaires dans une zone.

En revenant pour éditer CSS, je peux facilement trouver ce dont j'ai besoin en quelques secondes. La façon dont vous choisissez de grouper les styles dépend de vous, et c'est la beauté de ce système. J'ai quelques normes préétablies que j'ai énumérées ci-dessous:

• @resets - enlève les marges, le remplissage, les polices, les couleurs, etc. du navigateur.
• @fonts - paragraphes, titres, blockquotes, liens, code
• @navigation - les principaux liens de navigation du site principal
• @layout - wrapper, conteneur, barres latérales
• @header & @footer - ceux-ci peuvent varier en fonction de votre conception. Les styles possibles comprennent les liens et les listes non ordonnées, les colonnes de pied de page, les en-têtes et les sous-navigations.

Lors du regroupement des feuilles de style, j'ai trouvé le système de marquage peut aider beaucoup. Cependant, contrairement à PHP ou JavaScript, j'utilise un seul @groupe tag suivi d'une catégorie ou de mots-clés. J'ai inclus 2 exemples ci-dessous afin que vous puissiez avoir une idée de ce que je veux dire.

/ ** @group footer * / #footer styles…

/ ** @group footer, petites polices, colonnes, liens externes ** / 

Vous pouvez également ajouter un peu plus de détails dans chaque bloc de commentaires. Je choisis de garder les choses simples et simples les feuilles de style sont donc faciles à parcourir. Commenter est une question de documentation, donc tant que vous comprenez l'écriture, vous pouvez continuer.!

4 conseils pour mieux commenter le style

Nous avons passé la première moitié de cet article à examiner les différents formats de commentaire de code. Discutons maintenant de quelques conseils généraux pour garder votre code propre, organisé et facile à comprendre..

1. Gardez tout lisible

Parfois, les développeurs oublient que nous écrivons des commentaires pour les humains à lire. Tous les langages de programmation que nous comprenons sont conçus pour les machines, il est donc fastidieux de les convertir en texte écrit simple. Il est important de noter que nous ne sommes pas ici pour rédiger un document de recherche de niveau collégial, mais laissant juste des pourboires!

function getTheMail () // le code ici va générer un e-mail / * un code d'exécution si notre appel de fonction sendMyMail () personnalisé retourne true find sendMyMail () dans /libs/mailer.class.php, nous vérifions si l'utilisateur remplit tous les champs et le message est envoyé! * / if (sendMyMail ()) return true; // garder la valeur true et afficher le succès à l'écran

Même quelques mots suffisent mieux que rien. Quand vous retournez pour éditer et travaillez sur des projets dans le futur, il est souvent surprenant de voir combien vous allez oublier. Puisque vous ne regardez pas les mêmes variables et les mêmes noms de fonction tous les jours, vous avez tendance à oublier lentement la majorité de votre code. Ainsi vous pouvez ne laissez jamais trop de commentaires! Mais vous pouvez laisser trop de mauvais commentaires.

En règle générale, prenez le temps de réfléchir et de réfléchir avant d'écrire. Demande toi ce qui est le plus déroutant dans le programme et comment pouvez-vous mieux l'expliquer dans “mannequin” la langue? Considérer également pourquoi vous écrivez le code exactement comme vous êtes.

Certaines des erreurs les plus déroutantes apparaissent lorsque vous oubliez le but des fonctions personnalisées (ou tierces). Laisse une piste de commentaire menant à quelques autres fichiers si cela vous aidera à vous souvenir de la fonctionnalité plus facilement.

2. Alléger de l'espace!

Je ne saurais trop insister sur l'importance de les espaces peut être. Ça va doublement vrai pour les développeurs PHP et Ruby qui travaillent sur d’énormes sites Web contenant des centaines de fichiers. Vous regarderez ce code toute la journée! Ne serait-ce pas formidable de pouvoir parcourir les zones importantes?

$ dir1 = "/ home /"; // définit le répertoire de base principal $ myCurrentDir = getCurDirr (); // définit le répertoire de l'utilisateur actuel $ userVar = $ get_username (); // nom d'utilisateur actuel

Dans l'exemple ci-dessus, vous remarquerez le remplissage supplémentaire que j'ai placé entre les commentaires et le code sur chaque ligne. Au fur et à mesure que vous faites défiler les fichiers, ce style de commentaire se démarquer clairement. Il facilite la recherche d'erreurs et la correction de votre code des centaines de fois quand les blocs variables sont si nettoyer.

Vous pourriez effectuer une tâche similaire sur le code à l'intérieur d'une fonction où vous ne comprenez pas comment cela fonctionne, mais cette méthode encombrerait éventuellement votre code avec des commentaires en ligne, et c'est tout le contraire de bien ordonnée! Je recommande dans ce scénario ajout d'un grand commentaire de bloc autour du domaine de la logique.

$ (document) .ready (function () $ ('. sub'). hide (); // masquer la sous-navigation sur pageload / ** rechercher un événement de clic sur une ancre dans .itm div empêcher le lien par défaut action pour que la page ne change pas au clic, accédez à l’élément parent de .itm suivi de la liste suivante .sub pour ouvrir / fermer ** / $ ('. itm a'). live ('clic', fonction (e ) e.preventDefault (); $ (this) .parent (). next ('. sub'). slideToggle ('fast');););

Ceci est un petit morceau de code jQuery ciblant un sous-menu de navigation coulissante. Le premier commentaire est en ligne pour expliquer pourquoi nous cachons tous les .sous Des classes. Au-dessus du gestionnaire d'événements de clic en direct, j'ai utilisé un commentaire de bloc et mis en retrait toute l'écriture au même point. Cela rend les choses plus jolies que les paragraphes superflus - surtout pour les autres lecteurs de vos commentaires.

3. Commentaire en cours de codage

Avec un espacement approprié, cela peut être l’une des meilleures habitudes à adopter. Personne ne veut revenir sur son programme après son travail et documenter chaque élément. La plupart d'entre nous ne veulent même pas revenir en arrière et documenter les zones confuses! Cela prend vraiment beaucoup de travail.

Mais si vous pouvez écrire les commentaires pendant le codage tout sera encore frais dans votre esprit. En règle générale, les développeurs restent bloqués sur un problème et parcourent le Web pour trouver la solution la plus simple. Lorsque vous frappez le moment Eureka et que vous résolvez un tel problème, il est généralement clair que vous comprenez vos erreurs précédentes. Ce serait le meilleur temps laisser des commentaires ouverts et honnêtes sur votre code.

De plus, cela vous permettra de vous habituer à commenter tous vos fichiers. Le temps requis pour comprendre comment quelque chose fonctionne est beaucoup plus long une fois que vous avez déjà créé la fonction.. Vos futurs collaborateurs et vos coéquipiers vous remercieront d’avoir laissé des commentaires à l’avance..

4. Traiter les erreurs de buggy

Nous ne pouvons pas tous rester devant l'ordinateur pendant des heures à écrire du code. Je suppose que nous pouvons essayer, mais à un moment donné, nous devons dormir! Vous devrez probablement vous séparer de votre code pour la journée, certaines fonctionnalités étant toujours défectueuses. Dans ce scénario, il est crucial que vous laisser de longs commentaires détaillés sur l'endroit où vous avez laissé les choses.

Même après une nouvelle nuit de sommeil, vous serez peut-être surpris de la difficulté avec laquelle il peut être difficile de revenir au code. Par exemple, si vous construisez une page de téléchargement d’image et devez la laisser incomplète, vous devez devrait commenter à quel endroit du processus vous vous êtes arrêté. Les images sont-elles téléchargées et stockées dans la mémoire temporaire? Ou peut-être qu'ils ne sont même pas reconnus dans le formulaire de téléchargement, ou peut-être qu'ils ne s'affichent pas correctement sur la page après le téléchargement.

Commenter les erreurs est important pour deux raisons principales. D'abord vous pouvez ramasser facilement où vous avez laissé et essayez à nouveau frais pour résoudre le (s) problème (s). Et deuxièmement, vous pouvez différencier la version de production en direct de votre site Web des tests. Rappelez-vous que les commentaires doivent être utilisés pour explique pourquoi tu fais quelque chose, pas exactement ce qu'il fait.

Conclusion

Le développement d'applications et de logiciels Web est une pratique satisfaisante, bien que difficile. Si vous êtes l'un des rares développeurs qui comprennent vraiment les logiciels de construction, il est important de développer vos compétences en matière de codage.. Laisser des commentaires descriptifs n’est qu’une bonne pratique à long terme, et vous ne le regretterez probablement jamais!

Si vous avez des suggestions pour des commentaires de code plus clairs, veuillez nous en informer dans la zone de discussion ci-dessous.!