WordPress: Comment commenter votre code comme un pro : bonnes pratiques et bonnes habitudes

WordPress: Comment commenter votre code comme un pro : bonnes pratiques et bonnes habitudes

Écrire du code, c’est un peu comme écrire de la prose. Chaque personne le fait un peu différemment, et à cause de cela, nous avons tous une voix distincte lorsque notre code est lu. Nous avons différentes conventions de nommage et différentes logiques de résolution de problèmes. Nous pensons tous que notre code a du sens – surtout s’il fonctionne – mais quelqu’un d’autre pourrait ne pas le faire. Pour lutter contre cela, nous devons tous nous améliorer dans les commentaires de code source. De cette façon, quiconque viendra à côté du projet aura un chemin clair pour comprendre et améliorer/réparer notre code.

Comment commenter le code – Les bases

Pour commencer, assurons-nous que nous sommes tous sur la même longueur d’onde en ce qui concerne les commentaires. Dans cet article, nous discuterons des commentaires en ligne dans les scripts eux-mêmes. Des trucs comme ça dans un fichier CSS, par exemple, où le code lisible est décomposé par des commentaires qui sont ignorés par les processeurs.

/** Body Element Styling **/

body {color:red;}

h1 {size:17px;}


/** Sidebar Widget Styling**/

#email-signup-1 {text-transform:uppercase;}

Chaque langage de programmation a une manière différente de commenter le code source. PHP et HTML et JavaScript et C# ont tous des symboles légèrement différents qui commencent et terminent le code. Bien qu’il existe également des pratiques spécifiques à la langue, elles sont plus partagées qu’autrement.

Nous discuterons de certains des différents types de commentaires que vous rencontrerez, de leurs utilisations et des meilleures pratiques (ou peut-être simplement de bonnes habitudes à adopter) lorsque vous les utilisez vous-même.

Les principes de base pour commenter votre code sont simples :

  • Faites les brefs
  • Gardez-les pertinents
  • Utilisez-les généreusement, mais pas à l’excès

Si vous pouvez garder cela à l’esprit, vous vous en sortirez plutôt bien.

Un moment pour discuter des opposants

Très brièvement, abordons le code source commentant les opposants. Il existe un sous-ensemble non restreint de développeurs qui pensent que commenter votre code devrait être une occasion exceptionnellement rare. Que lorsque vous avez besoin de commentaires sur le code source, cela indique que votre code est faible d’une manière ou d’une autre. Que vos conventions de nommage, votre logique ou autre chose ne soient pas aussi transparents qu’ils devraient l’être.

Et, pour être juste, cet argument a un certain sens. Cependant, il existe un certain nombre de circonstances qui constituent un argument plus que suffisant pour inclure de la documentation sous forme de commentaires, quelle que soit la qualité de l’écriture et de la factorisation de votre code.

Les principaux étant que vous ne serez pas toujours celui qui travaillera sur le projet, et vous ne pouvez pas garantir l’expérience de la prochaine personne. Même si vous écrivez du bon code, il y a un risque de confusion et d’ambiguïté.

Documentation du bloc d’en-tête

Si vous regardez dans certains fichiers, le code ne commence pas immédiatement car il y a un gros en-tête dans le fichier qui décrit son objectif, les variables, les fonctions, les méthodes, etc. Ils pourraient même être dans une boîte géante autour d’elle pour attirer votre attention sur elle.

Ce n’est pas une bonne habitude à prendre. Parce que c’est un peu inutile. Eh bien, c’est vraiment inutile, en fait.

bonnes pratiques pour commenter votre code

Regardez également l’exemple ci-dessus : l’en-tête du commentaire est absurdement long. Il y a très rarement des raisons de le faire. Alors non.

Tout ce que vous mettriez dans ce fichier devrait être mis dans votre documentation de toute façon. L’avoir dans un commentaire est redondant. De plus, l’utilisateur final n’entrera probablement jamais dans votre code source, de sorte que le commentaire ne serait vu que par les autres développeurs (ou les utilisateurs inconditionnels du logiciel qui connaissent déjà la documentation).

De plus, chaque fois que la documentation change, vous devez la modifier dans ce fichier. Il est facile de rater une étape, et votre base de code peut alors être sérieusement encrassée.

Quand les commentaires d’en-tête sont utiles

Les commentaires d’en-tête sont utiles dans le code source pour des explications simples sur ce à quoi s’attendre dans ce fichier. Par exemple, il s’agit d’un script fourni avec un moteur de développement de jeu appelé RPG Maker, et le fichier JS principal qui contrôle chaque scène de jeu commence comme ceci :

//=============================================================================
// rpg_scenes.js v1.6.2
//=============================================================================

//=============================================================================

/**
 * The Superclass of all scenes within the game.
 * 
 * @class Scene_Base
 * @constructor 
 * @extends Stage
 */
function Scene_Base() {
    this.initialize.apply(this, arguments);
}

Scene_Base.prototype = Object.create(Stage.prototype);
Scene_Base.prototype.constructor = Scene_Base;

En outre, notez que le numéro de version est répertorié tout en haut. Faites ceci. Cependant, ne fournissez pas une liste complète des dates auxquelles le fichier a été modifié et les nouvelles versions publiées. Cela est enregistré dans Git ou dans un autre logiciel de contrôle de version, et il devrait être disponible pour toute personne ayant besoin de ces informations. Le numéro de version est suffisant pour la plupart des personnes qui consulteraient ce fichier.

Documentation en ligne

Le type de commentaire de code source le plus courant est le commentaire en ligne. Il y a une ligne fine avec ceux-ci entre faire les choses correctement, aller trop loin ou être trop économe avec eux. C’est un équilibre que vous devez simplement apprendre au fil du temps, mais il y a de très bonnes règles à prendre en compte.

Ne faites pas de commentaires ligne par ligne. Le commentaire en ligne est une chose. Le commentaire ligne par ligne rend le code presque illisible. Voir ci-dessous:

C’est exagéré. Si vous devez le faire, faites-le avant ou après la fonction. Mais pas sur chaque ligne. Il est envahissant et généralement inutile. Un commentaire avant la fonction (ou l’élément) est bon pour l’organisation et la clarté. Plus que cela devrait aller dans la documentation.

Si vous pensez qu’il est nécessaire de documenter, quelque chose comme ça suffira.

Les opposants mentionneront que même ce genre de commentaire est redondant car de bonnes conventions de nommage pour vos fonctions, variables et méthodes rendront le code lisible. C’est vrai jusqu’à un certain point, mais si vous voulez garder l’ambiguïté à son minimum absolu, un commentaire rapide est la voie à suivre.

Il est correct de mettre des avertissements dans les commentaires du code source

Parfois, la solution évidente à un problème ne résout pas réellement le problème. Dans ces cas, les développeurs qui viennent à un projet plus tard dans le développement peuvent regarder un fichier et envisager de le refactoriser en évident Solution. Ce sera une perte de temps totale.

Ou peut-être que quelque chose d’autre arrivera dans le futur, et ils essaieront d’appeler une fonction qui casse tout et met le projet à genoux.

Quoi qu’il en soit, si vous savez que quelque chose ne fonctionnera pas et que vous savez que d’autres personnes essaieront probablement à l’avenir, vous pouvez les avertir.

// Don't bother trying to use goodCodeComment() here. 
// It breaks bestPractices() despite seeming like the best option.
// We went with simplyOkayCodeComment() instead.

function simpleOkayCodeComment() {
	//some kind of code goes here
}

Aussi, avez-vous remarqué ce que nous avons fait dans cet exemple ? Nous avons non seulement donné l’avertissement aux futurs développeurs, mais nous avons également inclus un commentaire d’espace réservé au milieu d’une fonction. Étant donné que les commentaires du code source sont ignorés, vous pouvez les utiliser pour conserver le texte de l’espace réservé dans le fichier (en quelque sorte comme une annotation pour vous-même pour y revenir, ou comme exemple pour quelqu’un comme explication).

Ne sois pas un imbécile

J’ai déjà vu cela se produire auparavant, en particulier dans des projets open source qui n’étaient pas très bien modérés. Quelqu’un trouvera un extrait de code moins que stellaire et utilisera un commentaire pour dénigrer l’auteur.

//This function looks like it was written by a third grader.
//It shouldn't work, but it does somehow. I don't want
//to fix it because I want you all to see how bad it is.

Ou peut-être qu’ils corrigent le code, mais incluent le code, simplement commenté, afin qu’ils puissent montrer leur code, tout en se moquant de l’auteur précédent.

//The old code was so bad, I just had to leave it here for you to see.
//I fixed it. My code is below. But look at this.

// function theMatrix() {
//	var neo = maybeTheOne.data + theOracle.data
//	if theOne() !== neo
//		return console.log("you got the gift, but it looks like you're waiting for something")
// }

Assurez-vous simplement de ne jamais faire cela. Même si vous pensez que vous êtes drôle ou que cela vous fait bien paraître, ce n’est pas le cas et ce n’est pas le cas.

La véritable utilité de commenter le code est que vous gardiez ce code à portée de main tout en essayant autre chose. Ou pour donner un exemple de ce qui n’a pas fonctionné auparavant afin que quelqu’un ne réessaye pas en vain.

Commentaires sur le code source pour

En général, est exécuté sur quatre langues différentes. HTML, CSS, PHP et JavaScript. Il est impératif d’utiliser les bons caractères pour les commentaires.

Pour le HTML :

En CSS :

/* Any number of lines will be a comment until the comment is closed */ 

PHP et JavaScript ont les mêmes méthodes pour faire des commentaires sur une ou plusieurs lignes :

ou

Conclusion

Si vous êtes dans les tranchées jour après jour, écrivant du code et poussant vers GitHub, votre organisation peut avoir un guide de style pour les commentaires qu'elle souhaite que vous suiviez. S'ils ne le font pas, cependant, ou si vous êtes seul, garder cela à l'esprit non seulement facilitera votre travail à l'avenir, mais aidera également tous ceux qui viendront après vous.

Quels sont vos trucs et astuces pour tirer le meilleur parti de commenter votre code ?

Article présenté en image par Skillup / shutterstock.com

// Google var et_first_script = document.getElementsByTagName( 'script' )[ 0 ]; var et_new_script = document.createElement( 'script' ); et_new_script.src = 'https://www.googletagmanager.com/gtag/js?id=AW-1006729916'; et_new_script.setAttribute('async', 'true'); et_first_script.parentNode.insertBefore( et_new_script, et_first_script ); window.onload = function(){ window.dataLayer = window.dataLayer || []; function gtag(){dataLayer.push(arguments);} gtag('js', new Date());

gtag('config', 'AW-1006729916'); };

// Twitter !function(e,t,n,s,u,a){e.twq||(s=e.twq=function(){s.exe?s.exe.apply(s,arguments):s.queue.push(arguments); },s.version='1.1',s.queue=[],u=t.createElement(n),u.async=!0,u.src='//static.ads-twitter.com/uwt.js', a=t.getElementsByTagName(n)[0],a.parentNode.insertBefore(u,a))}(window,document,'script'); twq('init','o0xq6'); twq('track','PageView');

}

All the CMS Templates You Could Ask For.

WordPress: Comment commenter votre code comme un pro : bonnes pratiques et bonnes habitudes

2M+ items from the worlds largest marketplace for CMS TemplatesEnvato Market.



WordPress: Comment commenter votre code comme un pro : bonnes pratiques et bonnes habitudes

#Comment #commenter #votre #code #comme #pro #bonnes #pratiques #bonnes #habitudes