Convention d’écriture JavaScript pour les projets Access42

Mode Strict

Sauf exception la syntaxe utilise le mode strict de JavaScript qui améliore certaines règles de syntaxe.

Les avantages principaux sont de remonter certaines erreurs, ignorées ou traitées directement par le navigateur, comme une déclaration de variable globale inappropriée, l’utilisation de deux noms identiques de paramètres de fonctions…

Pour plus de détails sur le mode strict vous pouvez consulter cet excellent papier sur le site Mozilla Developper Network.

Règles de style

Aérer et indenter correctement

Javascript sait parfaitement bien gérer l’absence d’espace dans les syntaxes composées, par exemple :

function illisible(a,b){var vartoto=a+b;
if(vartoto>Number(document.getElementById('toto').getAttribute('data-value'))){return vartoto;}else{return false;}}

Cet exemple est une syntaxe valide. À l’échelle d’un script cela rend le truc totalement illisible.

Pensez à éclaircir votre code en utilisant les espaces de manière appropriée, en indentant correctement ou en utilisant des variables intermédiaires pour éclaircir des paramètres conditionnels ou de fonctions :

function lisible( a, b ){
  var vartoto = a + b;
  var compare = Number( document.getElementById( 'toto' ).getAttribute( 'data-value' ) ) ;
  if( vartoto > compare ){
     return vartoto;
  }
  else{
     return false;
  }
}

Style camelCase

Nous avons adopté pour les déclarations de variables, les noms de fonctions ou de paramètre le style camelCase qui consiste à mettre une majuscule aux mots composants un nom, sauf au premier mot (pour une raison que nous verrons plus bas).

//Pas camelCase
var quantitemaximum;
//camelCase
var quantiteMaximum;

Convention de nommage des fonctions

JavaScript ne possédant pas encore de syntaxe spécifique pour déclarer un constructeur de classe, il est de convention de nommer les fonctions constructeurs avec une majuscule. Cela ne change rien, n’importe qu’elle fonction peut devenir un constructeur si elle est instanciée avec le mot clé new, mais cela facilite la lecture du code.

//Ce n'est pas un constructeur
function maFonction();
//C'est un constructeur
function MaFonction();

Commenter, commenter, commenter….

C’est sans doute la règle la plus importante pour rendre le code lisible par quelqu’un d’autre que vous, ou pour vous mêmes : il faut commenter son code.

Il n’est pas nécessaire de tout commenter, une fonction peut être facilement compréhensible en elle-même.

Il est toujours nécessaire de commenter les fonctions complexes ou les portions de code qui appellent plusieurs fonctions disséminées ailleurs. Et, lorsque c’est nécessaire donner un exemple d’instanciation en expliquant l’usage des paramètres, mêmes si ceux-ci vous paraissent triviaux.

Exemple de commentaire d’une fonction :

/*
  *** Component slider ***
   Constructor
        -required obj : slider component
        example : var slider = new Slider ( document.getElementById( 'my-slider' ) )
   Method set
        - required obj : slider component (this)
        - required keys : key event
        - required posOrigin : initial x offsetleft
        - required posMax : final right x position
        - required unit : value for aria-valuetext
        - required step : relative step unit
        example : slider.set( this, slider.keys, slider.posOrigin, slider.posMax, slider.unit, slider.step )
*/

Exemple dans le code :

// next event
if ( event.keyCode === keys.right || event.keyCode === keys.down ) {
  current + 1 >= maxTab ? next = 0 : next = current + 1;
}
// prev event
else if ( event.keyCode === keys.left || event.keyCode === keys.up ) {
  current - 1 < 0 ? next = maxTab - 1 : next = current - 1;
}

Conclusion

Ces quelques règles de bonne conduite seront d’une grande utilité pour conserver la lisibilité du code et favoriser le travail collaboratif. Nous sommes preneurs de toutes suggestions pour les améliorer.