Normes de programmation Javascript du Dojo Standardisez votre propre écriture JavaScript_Connaissances de base

Avant-propos

Les avantages de bonnes habitudes d'écriture JavaScript sont évidents. Aujourd'hui, Bingo recommande à tout le monde la spécification de programmation Javascript de Dojo. Il est recommandé que tout le monde puisse apprendre de cette spécification pour écrire du Javascript. Merci à i.feelinglucky pour la traduction.

Préface

Toute violation de ce guide est autorisée si elle améliore la lisibilité.

Tous les codes doivent être faciles à lire pour les autres.

Référence de lecture rapide

API principale Veuillez utiliser le style suivant :

结构	规则	注释
模块	小写	不要使用多重语义（Never multiple words）
类	骆驼
公有方法	混合	其他的外部调用也可以使用 lower_case()，这样的风格
公有变量	混合
常量	骆驼 或 大写

Structure

Règles

Commentaires

结构	规则
私有方法	混合，例子：_mixedCase
私有变量	混合，例子：_mixedCase
方法（method）参数	混合，例子：_mixedCase, mixedCase
本地（local）变量	混合，例子：_mixedCase, mixedCase

Module minuscule Jamais plusieurs mots Classe Chameau Méthodes publiques Mélange D'autres appels externes peuvent également utiliser lower_case(), ce style Variables publiques Mélange Constante Chameau ou chapiteau Bien que les éléments suivants ne soient pas nécessaires, ils sont recommandés : _mixedCase

Variables privées	Mixte, exemple : _mixedCase
Paramètres de méthode	Mixte, exemple : _mixedCase, MixedCase
Variables locales (locales)	Mixte, exemple : _mixedCase, MixedCase

Convention de dénomination

1. Les noms de variables doivent être en lettres minuscules.
2. La dénomination des classes utilise des règles de dénomination des chameaux, par exemple :

Compte, EventHandler

3. Les constantes doivent être déclarées devant l'objet (classe) ou la variable d'énumération. Les variables d'énumération doivent être nommées avec une signification réelle, et leurs membres doivent utiliser des règles de dénomination de chameau ou utiliser des lettres majuscules :

Copier le code Le code est le suivant :

var Types de nœuds = {
Élément : 1,
DOCUMENT : 2
>

4. Les mots abrégés ne peuvent pas utiliser de noms en majuscules comme noms de variables :

getInnerHtml(), getXml(), XmlDocument
5. La commande de la méthode doit être un verbe ou une phrase verbale :

obj.getSomeValue()
6. Les classes publiques doivent être nommées en utilisant des noms mixtes (mixedCase).
7. Les variables CSS doivent être nommées en utilisant les mêmes variables de classe publique auxquelles elles correspondent.
8. Les membres d'attribut variable des classes privées doivent être nommés avec un nom mixte (mixedCase) et précédés d'un trait de soulignement (_). Par exemple :

Copier le code Le code est le suivant :

var MaClasse = fonction(){
var _buffer;
this.doSomething = function(){
};
>

9. Si la variable est définie comme privée, un trait de soulignement doit être ajouté devant elle.

this._somePrivateVariable = déclaration;

10. Les variables universelles doivent utiliser des noms de types cohérents avec leurs noms :

setTopic(topic) // La variable topic est une variable de type Topic
11. Tous les noms de variables doivent utiliser des noms anglais.
12. Si la variable a une portée plus large (grande portée), elle doit utiliser une variable globale ; dans ce cas, elle peut être conçue comme membre d'une classe ; D'un autre côté, si la portée est petite ou si la variable est privée, utilisez un nom concis.
13. Si une variable a sa propre valeur de retour implicite, évitez d'utiliser ses méthodes similaires :

getHandler(); // Évitez d'utiliser getEventHandler()

14. Les variables publiques doivent exprimer clairement leurs propres attributs pour éviter les significations ambiguës des mots, par exemple :

MouseEventHandler
, pas MseEvtHdlr.
Veuillez prêter à nouveau attention à cette règle, les avantages de le faire sont très évidents. Il peut exprimer clairement le sens défini par l'expression. Par exemple :

dojo.events.mouse.Handler // au lieu de dojo.events.mouse.MouseEventHandler

15. La classe/constructeur peut être nommée en étendant le nom de sa classe de base, afin que le nom de sa classe de base puisse être trouvé correctement et rapidement :
Gestionnaire d'événements
UIEventHandler
Gestionnaire d'événements de souris
Une classe de base peut raccourcir son nom en partant du principe de décrire clairement ses propriétés :
​MouseEventHandler par opposition à MouseUIEventHandler.

Convention de dénomination spéciale

Le terme « get/set » ne doit pas être associé à un champ à moins qu'il ne soit défini comme une variable privée.
Les noms de variables précédés de « est » doivent être des valeurs booléennes, et de la même manière, ils peuvent être « a », « peut » ou « devrait ».
Le terme « calculer » en tant que nom de variable doit faire référence à une variable qui a été calculée.
Le terme « trouver » en tant que nom de variable fera référence à la variable pour laquelle la recherche a été effectuée.
Le terme « initialiser » ou « init » en tant que nom de variable doit faire référence à une classe ou à un autre type de variable qui a été instanciée (initialisée).
Les variables de contrôle UI (User Interface) doivent avoir le type de contrôle après le nom, par exemple : leftComboBox, TopScrollPane.
Les formes plurielles DOIVENT être utilisées pour nommer les collections.
Les noms de variables commençant par « num » ou « count » sont classiquement des nombres (objets).
Il est recommandé d'utiliser des variables portant des noms tels que « i », « j », « k » (et ainsi de suite) pour les variables répétées.
Les termes supplémentaires doivent utiliser des mots supplémentaires, tels que : obtenir/définir, ajouter/supprimer, créer/détruire, démarrer/arrêter, insérer/supprimer, commencer/fin, etc.
Utilisez des abréviations pour les noms qui peuvent être abrégés.
Évitez les noms de variables booléennes ambigus, par exemple :
isNotError, isNotFound est illégal
Il est recommandé d'ajouter « Exception » ou « Erreur » après le nom de la variable pour les classes d'erreur.
Si la méthode renvoie une classe, le nom doit indiquer ce qu'elle renvoie ; s'il s'agit d'une procédure, il doit indiquer ce qu'elle fait.

Fichier

Veuillez utiliser 4 taquets de tabulation pour l'indentation.
Si votre éditeur prend en charge les balises de fichiers, veuillez ajouter la ligne suivante pour rendre notre code plus facile à lire :

// vim:ts=4:noet:tw=0:
Note de traduction : Les étrangers utilisent davantage l'éditeur VIM, vous pouvez choisir de suivre cet article.

Le pliage du code doit paraître complet et logique :

Copier le code Le code est le suivant :

var uneExpression = Expression1
Expression2
Expression3;

var o = unObjet.get(
Expression1,
Expression2,
Expression3
);

Remarque : L'indentation des expressions et des déclarations de variables doit être cohérente.
Remarque : les paramètres de fonction doivent être explicitement indentés et les règles d'indentation doivent être cohérentes avec les autres blocs.

Variable

1. Les variables doivent être déclarées et initialisées avant de pouvoir être utilisées, même si elles sont de type NULL.
2. Les variables ne peuvent pas être ambiguës.
3. Les ensembles de variables associés doivent être placés dans le même bloc de code, et les ensembles de variables non liés ne doivent pas être placés dans le même bloc de code.
4. Les variables doivent essayer de conserver la durée de vie minimale.
5. Spécifications pour les variables en boucle/répétition :
   1. Si vous n'avez qu'un bloc de contrôle de boucle, vous devez utiliser une boucle FOR.
   2. Les variables de boucle doivent être initialisées avant le début de la boucle ; si vous utilisez une boucle FOR, utilisez l'instruction FOR pour initialiser les variables de boucle.
   3. Les déclarations « faire… pendant » sont autorisées.
   4. Les déclarations "break" et "continue" sont toujours autorisées (mais soyez conscient).
6. Expression conditionnelle
   1. Les expressions conditionnelles complexes doivent être évitées autant que possible et des variables booléennes temporaires peuvent être utilisées si nécessaire.
   2. Le cas nominal DEVRAIT être placé dans la partie « if » et l'exception dans la partie « else » d'une instruction « if ».
   3. Les blocs dans les expressions conditionnelles doivent être évités.
7. Divers
   1. Essayez d'éviter les nombres magiques, ils doivent être remplacés par des constantes.
   2. Les variables à virgule flottante doivent spécifier une décimale (même si elle est 0).
   3. Les variables à virgule flottante doivent spécifier la partie réelle, même si elles sont nulles (utilisez un 0 non significatif).

Mise en page

Bloquer

Un extrait de code normal devrait ressembler à ceci :

Copier le code Le code est le suivant :

pendant que (!isDone){
faireQuelquechose();
isDone = moreToDo();
>

L'instruction IF devrait ressembler à ceci :

Copier le code Le code est le suivant :

si (uneCondition){
déclarations ;
} sinon si (someOtherCondition){
déclarations ;
} autre {
déclarations ;
>

Une instruction FOR devrait ressembler à ceci :

Copier le code Le code est le suivant :

pour (initialisation ; condition ; mise à jour){
déclarations ;
>

L'instruction WHILE devrait ressembler à ceci :

Copier le code Le code est le suivant :

pendant que (!isDone) {
faireQuelquechose();
isDone = moreToDo();
>

L'instruction DO… WHILE devrait ressembler à ceci :

Copier le code Le code est le suivant :

faire {
déclarations ;
} while (condition);

L'instruction SWITCH devrait ressembler à ceci :

Copier le code Le code est le suivant :

interrupteur (état) {
cas ABC :
déclarations ;
// échec
cas DEF :
déclarations ;
pause;
par défaut :
déclarations ;
pause;
>

L'instruction TRY… CATCH devrait ressembler à ceci :

Copier le code Le code est le suivant :

essayez {
déclarations ;
} attraper(ex) {
déclarations ;
} enfin {
déclarations ;
>

Les instructions IF – ELSE, WHILE ou FOR sur une seule ligne doivent également avoir des parenthèses, mais elles peuvent être écrites comme ceci :
if (condition){ déclaration ; }
while (condition){ déclaration ; }
for (initialisation; condition; mise à jour){ instruction; }

Vierge

Il est recommandé de séparer l'opérateur
1. par des espaces (y compris l'opérateur ternaire).
2. Évitez d'utiliser des espaces pour séparer les mots-clés suivants :
   • pause
   • attraper
   • continuer
   • faire
   • autre
   • enfin
   • pour
   • fonction (s'il s'agit d'une fonction anonyme, par exemple : var foo = function(){}; )
   • si
   • retour
   • interrupteur
   • ce
   • essayer
   • vide
   • pendant
   • avec
3. Les mots-clés suivants doivent être séparés par des espaces :
   • cas
   • par défaut
   • supprimer
   • fonction (si c'est une déclaration, par exemple : function foo(){}; )
   • dans
   • instance de
   • nouveau
   • lancer
   • type de
   • var
4. Il est recommandé de séparer la virgule (,) par des espaces.
5. Côlon (:) Il est recommandé d'utiliser des espaces blancs pour séparer.
6. Il est recommandé de séparer le point (.) à la fin par un espace blanc.
7. Point (.) Évitez d'utiliser des espaces à l'avant.
8. Les appels de fonctions et les méthodes évitent d'utiliser des espaces, par exemple : doSomething(someParameter); // au lieu de doSomething (someParameter)
9. Utilisez des lignes vides entre les blocs logiques.
10. Il est recommandé d'aligner les déclarations pour les rendre plus faciles à lire.

Remarques

1. Code saccadé Il n'est pas nécessaire de ajouter des commentaires. Vous devez d'abord réécrire Eux.
Veuillez utiliser l'anglais pour tous les commentaires.
Des solutions résolues aux fonctionnalités inexploitées, les commentaires
3. doivent être pertinents par rapport au code.
Après un grand nombre de déclarations de variables
4. doit être suivi d'un commentaire.
Le commentaire doit expliquer l'utilité de l'extrait de code, en particulier l'extrait de code suivant.
Commentaires
6. Il n'est pas nécessaire d'ajouter sur chaque ligne.

Documentation

Ce qui suit fournit quelques méthodes de base de description de fonctions ou d'objets :

Résumé : Décrivez brièvement le but de cette fonction ou de cet objet

Description : Une brève description de cette fonction ou classe
Retour : décrit ce que cette fonction renvoie (sans compter le type de retour)
Informations sur les fonctions de base

Copier le code Le code est le suivant :

fonction(){
// résumé : Bientôt, nous aurons suffisamment de trésors pour gouverner tout le New Jersey.
// description : Ou nous pourrions simplement trouver un nouveau colocataire.
// Écoute, va le trouver. Il ne te crie pas dessus.
// Tout ce que j'essaie de faire, c'est de le faire sourire et de chanter
// lui et danse autour de lui et il s'allonge sur moi.
// Il m'a dit d'entrer dans le congélateur parce qu'il y avait un carnaval là-dedans.
// renvoie : Regardez, une cassette Bananarama !
>

Informations sur la fonction de l'objet

Aucune description de la valeur de retour

Copier le code Le code est le suivant :

{
// résumé : Dingle, engage la machine arc-en-ciel !
// description :
// Je te dis quoi, j'aurais aimé être... oh mon dieu... ce rayon,
// à venir comme ça, la vitesse, tu voudras peut-être ajuster ça.
// Ça m'a vraiment fait un numéro dans le dos, là, je veux dire, et je ne le fais pas
// je veux dire coup du lapin, pour l'instant, parce que c'est un peu trop loin,
// mais, tu es assuré, non ?
>

Déclaration de fonction

Dans certains cas, les appels de fonctions et les déclarations sont invisibles. Dans ce cas, nous n'avons aucun moyen d'ajouter des instructions à la fonction (pour que le programme l'appelle). Si vous rencontrez cette situation, vous pouvez utiliser une classe pour encapsuler la fonction.

Remarque : Cette méthode ne peut être utilisée que lorsque la fonction n'a aucun paramètre initialisé. Dans le cas contraire, ils sont ignorés.

Copier le code Le code est le suivant :

dojo.declare(
"foo",
nul,
{
// résumé : Ouf, c'est vraiment relaxant, Frylock.
// description :
//Il y a des milliers d'années, avant l'aube de
// mec tel qu'on le connaissait, il y avait Monsieur le Père Noël : un
// créature ressemblant à un singe fabriquant des jouets grossiers et inutiles
// d'os de dinosaures, les lançant sur des créatures ressemblant à des chimpanzés avec
// mains froissées quel que soit leur comportement
// année précédente.
// revient : À moins que Carl ne rende hommage aux Anciens Elfes dans l'espace.
>
);

Paramètres

1. Type simple
   Les paramètres de type simple peuvent être annotés directement dans la définition des paramètres de fonction.
   [cc lang="javascript"]fonction(/*String*/ foo, /*int*/ bar)...
   Paramètres de type variable
   ​ Voici quelques modificateurs pour référence :
   ? Paramètres facultatifs
   … Il a dit que la gamme de paramètres des nouilles est incertaine
   Tableau
   fonction(/*String?*/ foo, /*int...*/ bar, /*String[]*/ baz)...
   Description du paramètre global
   Si vous souhaitez ajouter une description, vous pouvez les déplacer vers le bloc d'initialisation.
   Le format d'information de base est : *clé* champ de description (*clé* Phrase descriptive)
   Le format des paramètres et des variables est : *key* ~*type*~ champ de description (*key* ~*type*~ Phrase descriptive)
   Remarque : *Keyword* et ~*Type*~ peuvent être exprimés à l'aide de n'importe quelle lettre ou chiffre.
   Copier le code Le code est le suivant :
   
   fonction (foo, bar) {
   // foo : Chaîne
   // utilisé comme premier paramètre
   // barre : int
   // utilisé comme deuxième paramètre
   >
   

   Variable

   Étant donné que la déclaration des variables d'instance, des variables prototypes et des variables externes est cohérente, il existe de nombreuses façons de déclarer et de modifier des variables. La définition et le positionnement spécifiques doivent indiquer le nom, le type, la portée et d'autres informations de la variable là où elle apparaît pour la première fois.

   Copier le code Le code est le suivant :
   
   fonction foo() {
   // maChaîne : Chaîne
   // fois : int
   // Combien de fois imprimer myString
   // séparateur : String
   // Que faut-il imprimer entre myString*
   this.myString = "texte d'espace réservé";
   ceci.fois = 5;
   >
   foo.prototype.setString = fonction (myString) {
   this.myString = maChaîne;
   >
   foo.prototype.toString = function() {
   pour (int i = 0; i < this.times; i ) {
   dojo.debug(this.myString);
   dojo.debug(foo.separator);
   >
   >
   foo.separator = "=====";
   

   Annotations variables dans les objets

   doit être marqué de la même manière que les valeurs et méthodes des objets, par exemple lorsqu'elles sont déclarées :

   Copier le code Le code est le suivant :
   
   {
   // clé : Chaîne
   // Une valeur simple
   clé : "valeur",
   // clé2 : Chaîne
   // Une autre valeur simple
   >
   

   Valeur de retour

   Étant donné qu'une fonction peut renvoyer plusieurs valeurs (types) différentes en même temps, un commentaire de type de retour doit être ajouté après chaque valeur de retour. Des commentaires peuvent être faits dans la ligne. Si toutes les valeurs de retour sont du même type, indiquez le type de retour ; s'il existe plusieurs valeurs de retour différentes, marquez le type de retour comme "mixte".

   Copier le code Le code est le suivant :
   
   fonction() {
   si (arguments.longueur) {
   return "Vous avez passé des arguments" ; // String
   } autre {
   return false; // Booléen
   >
   >
   

   Pseudocode (à discuter)

   Parfois, vous devez ajouter une description de processus fonctionnel pour cette fonction ou cette classe dans une fonction ou une classe. Si vous prévoyez de faire cela, vous pouvez utiliser /*======== (= le caractère apparaît de préférence 5 fois ou plus), ce qui a l'avantage de ne pas avoir à ajouter ces éléments au code (Annotation : auteur original Cela signifie probablement un système de gestion de code).

   Il semble qu'il y aura un très long commentaire dans /*====== et =====*/. Vous pouvez envisager de le supprimer une fois l'ajustement de la fonction terminé.
   

   Copier le code Le code est le suivant :
   
   /*=====
   module.pseudo.kwArgs = {
   //url : Chaîne
   // L'emplacement du fichier
   URL : "",
   // mimeType : Chaîne
   // texte/html, texte/xml, etc
   mimeType : ""
   >
   =====*/

   fonction(/*module.pseudo.kwArgs*/ kwArgs){
   dojo.debug(kwArgs.url);
   dojo.debug(kwArgs.mimeType);
   >
   

   Lien original : http://dojotoolkit.org/developer/StyleGuide
   Traduit par : i.feelinglucky{at}gmail.com de http://www.gracecode.com