Sélectionner une page


L’écriture de code est similaire à l’écriture de prose. Tout le monde le fait un peu différemment, et c’est pourquoi nous avons tous des voix différentes lorsque notre code est lu. Nous avons différentes conventions de dénomination 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 ne le peut pas. Pour contrer cela, nous devons tous améliorer la façon dont nous commentons le code source. De cette façon, tous ceux qui accompagnent le projet ont un chemin clair pour comprendre et améliorer / corriger notre code.

Comment commenter le code – Les bases

Tout d’abord, assurons-nous que nous sommes tous sur la même page pour les commentaires. Cet article couvre les commentaires en ligne dans les scripts eux-mêmes. De telles choses, par exemple, dans un fichier CSS dans lequel le code lisible est divisé par des commentaires 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, ainsi que JavaScript et C #, ont des symboles légèrement différents qui commencent et terminent le code. Bien qu’il existe des pratiques spécifiques à une langue, elles sont plus courantes qu’improbables.

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

Les principes de base pour commenter votre code sont simples:

  • Faites-les court
  • Gardez-les pertinents
  • Utilisez-les généreusement, mais pas trop

Si vous pouvez garder cela à l’esprit, vous serez plutôt bon.

Un moment pour discuter des opposants

Passons donc très brièvement au code source commentant les opposants. De nombreux développeurs pensent que commenter votre code devrait être une opportunité exceptionnellement rare. Si 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 votre convention de dénomination, votre logique ou toute autre chose n’est pas aussi transparente qu’elle devrait l’être.

Et pour être juste, cet argument a du sens. Cependant, il existe un certain nombre de circonstances qui font 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 prise en compte de votre code.

Les plus importants sont que vous n’êtes pas toujours celui qui travaille sur le projet et vous ne pouvez pas garantir les compétences de la prochaine personne. Même si vous écrivez un 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 démarre pas immédiatement car le fichier a un gros en-tête qui décrit l’objectif, les variables, les fonctions, les méthodes, etc. Ils pourraient même être dans une énorme boîte pour attirer votre attention.

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

Bonnes pratiques pour commenter votre code

Jetez également un œil à l’exemple ci-dessus: l’en-tête du commentaire est absurdement long. Il y a très rarement des raisons pour cela. Alors ne le fais pas.

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

Si la documentation change, vous devrez la modifier dans ce fichier. Il est facile de rater une étape et votre base de code peut être gravement polluée.

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

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


//=============================================================================
// 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;


Notez également que le numéro de version est indiqué en haut. Faites ça. Cependant, ne fournissez pas une liste complète des dates auxquelles le fichier a été modifié et de nouvelles versions publiées. Ceci est enregistré dans Git ou dans un autre logiciel de contrôle de version et devrait être accessible à 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 entre faire bien, aller trop loin ou être trop frugal avec eux. C’est un équilibre à apprendre au fil du temps, mais il y a de très bonnes règles de base à garder à l’esprit.

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



function sourceCodeComment () { //calls a function
  var comment = document.getElementbyID("Code Comment").value; // declares a variable
  if (comment != null && comment != '') {  //starts an if statement to evaluate if there's a comment
        return console.log("Thank you for your comment.") //prints a string to the console
}


C’est une exagération. Si vous devez le faire, faites-le avant ou après la fonction. Mais pas dans toutes les lignes. C’est intrusif 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 que la documentation est nécessaire, quelque chose comme ça suffit.


//checks to see if there's a comment. If so, returns a thank you message.

function sourceCodeComment () {
  var comment = document.getElementbyID("Code Comment").value; 
  if (comment != null && comment != '') { 
        return console.log("Thank you for your comment.")
}


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

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

Parfois, la solution évidente à un problème ne résout pas vraiment le problème. Dans ces cas, les développeurs arrivant à un projet plus tard dans le développement peuvent consulter un fichier et envisager de le réviser. évidemment Solution. C’est une perte de temps.

Ou peut-être que quelque chose d’autre apparaîtra dans le futur et qu’ils essaient d’invoquer une fonction qui casse tout et met le projet à genoux.

Que vous ayez quelque chose qui ne fonctionnera pas et que vous savez que d’autres personnes essaieront probablement à l’avenir, vous pouvez les en 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
}


Avez-vous remarqué ce que nous avons fait dans cet exemple? Non seulement nous avons averti les futurs développeurs, mais nous avons également mis 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 d’espace réservé dans le fichier (une sorte de note à laquelle vous pouvez revenir ou un exemple à expliquer à quelqu’un).

Ne sois pas idiot

J’ai déjà vu cela, en particulier sur les projets open source qui n’étaient pas particulièrement bien modérés. Quelqu’un trouvera un extrait de code moins qu’exceptionnel et utilisera un commentaire pour désagréger 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 ajoutent le code qui est simplement commenté afin qu’ils puissent afficher 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 et ce n’est pas le cas.

Le vrai code de commentaire est d’avoir ce code à portée de main pendant que vous essayez autre chose. Ou pour donner un exemple de ce qui n’a pas fonctionné avant pour que quelqu’un ne réessaye pas sans succès.

Commentaires sur le code source pour WordPress

En général, WordPress fonctionne dans quatre langues différentes. HTML, CSS, PHP et JavaScript. Assurez-vous d’utiliser les bons caractères pour les commentaires.

Pour HTML:

<!-- comments go here and can be single or on multiple lines --></em>

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 créer des commentaires simples et multilignes:

<?php function(); // a single line comment is like this ?>

ou alors

<?php /* unlike above, you can carriage return
				and no matter how many lines you use,
					the comment won't stop until closed */

Conclusion

Si vous êtes dans les tranchées jour après jour, en écrivant du code et en poussant sur GitHub, votre organisation peut avoir un guide de style pour les commentaires à suivre. Cependant, si ce n’est pas le cas ou si vous êtes seul, non seulement garder ces choses à l’esprit facilitera votre travail à l’avenir, mais cela aidera également tous ceux qui viendront après vous.

Quels sont vos trucs et astuces pour tirer le meilleur parti des commentaires sur votre code?

Article avec photo de Skillup / shutterstock.com





Source link

Recent Posts