Voici de l'article que j'ai rédigé pour Flash Forum concernant certaines conventions utilisées par les programmeurs pour rendre leur code lisible.

Je me suis inspiré pour ca tout d'abord de mon expérience de programmeur, puis du simplebon sens, et ensuite de conseils avisé d'autres programmeurs sur de petits oublis. Cet article donne donc la plupart des conseils nécessaires pour produire un code clair, et donc facile à maintenir.
Car on ne le dira jamais assez, le premier bénéficiaire d'un code propre, c'est bien le programmeur lui-même !!!

Les conventions de présentation du code

Auteur : LAlex
Mail : lalex@flash-forum.net
URL : http://www.flash-forum.net
Date de création : 31/07/2003
Version : Flash 5 / MX

Présentation

"Un bon code est un code que l'on peut comprendre sans connaître le langage utilisé ..."

Le but de ce tutoriel est de vous présenter des conventions de codage à utiliser avec ActionScript. Elles sont utilisées dans leur plus grande partie par les programmeurs du monde entier, sur la plupart des langages informatiques. Ces conventions n'ont rien d'obligatoires, elles permettent seulement de vous faciliter la relecture de votre code, et de permettre à n'importe quel autre programmeur ActionScript (ou autre) de le comprendre facilement. Voici les différents points à prendre en compte :

1. Les conventions de nommage des variables
2. Les conventions de nommage des classes
3. Les conventions de nommage des méthodes
4. Les conventions d'indentation du code
5. Les conventions de ciblage des variables
6. Les conventions de commentaires
7. Conseils supplémentaires
8. Les considérations sur le poids des animations
9. Conclusion

• Annexe A : Les mots réservés
• Annexe B : Les mots déconseillés

1. Les conventions de nommage des variables

ATTENTION N'UTILISEZ JAMAIS D'ACCENTS DANS VOS NOMS DE VARIABLES !

Les noms de variables commencent par une minuscule. Les différents "mots" qui composent le nom de cette variables commencent eux par une majuscule. L'underscore ( '_' ) est parfois utilisé comme séparateur de "mots", mais rend les noms de variables plus longs. Cette pratique est maintenant assez rare : // Variable correctement ncaommée
var numeroDeDossard = 10;
// Variable bien nommée, mais peu pratique
var numero_de_dossard = 10;
// (!) Variable mal nommée
var numerodedossard = 10; Choisissez des noms de variables explicites, qui décrivent le rôle de la variable ://Variable correctement nommée
var jourDeLaSemaine = "Lundi";
// (!) Variable mal nommée
var toto = "Lundi" Excluez les noms tels que 'toto', 'tata', 'titi'. Les noms de variables en une seule lettre sont à exclure également (sauf 'x' et 'y' pour des coordonnées...). Une entorce à cette règle est souvent pratiquée pour les boucles 'for'. Beaucoup de programmeurs utilisent les noms de variable 'i', 'j' etc... pour leurs compteurs de boucle : for (var i=0 ; i<10 ; i++) {
   trace("Compteur de boucle : " + i);
} Dans la plupart des langages traditionnels, chaque variable doit avoir été déclarée avec son type. Pour pouvoir identifier le type de ces variables, les programmeurs font commencer les noms de variables par une abréviation du type. Ainsi, les variables numériques commencent par 'int', les tableaux par 'ar', les chaînes de caractères par 'str', les booléens par 'b' etc... Le typage dans Flash n'étant pas un "typage fort", peu de codeurs ActionScript utilisent cette convention.var intNumeroDeDossard = 10;
var arJoursDeLaSemaine = new Array("Lun", "Mar", "Mer", "Jeu", "Ven", "Sam", "Dim");
var dteAujourdhui = new Date();
var bEstArrive = true; Certains usages veulent aussi que les membres d'une classe soient préfixés avec m_ ... Cela permet de différencier, dans la méthode d'une classe, l'accés aux propriétés de l'objet et l'accés aux variables passées en paramètres ou aux variables locales. Tout comme la précédente, cette convention est peu utilisée en Flash, ou fait place à un underscore tout seul au début de la propriété (comme '_x' et '_y' dans la classe MovieClip)._global.Course = function(nbCoureurs) {
   this.m_arCoureurs = new Array(nbCoureurs);
} 2. Les conventions de nommage des classes ATTENTION N'UTILISEZ JAMAIS D'ACCENTS DANS VOS NOMS DE CLASSES ! Les mêmes règles que les noms de variables s'appliquent pour les noms de classes, sauf que les noms de classes commencent par une majuscule. Certains programmeurs (comme fred : cf tuto de création des classes) commencent systématiquement les noms de classes avec un 'C' majuscule. Quel que soit le choix que vous faites, les deux solutions sont lisibles et comprises par les programmeurs.// Classe correctement nommée
_global.Course = function(nbCoureurs) {
   this.arCoureurs = new Array(nbCoureurs);
}
// (!) Classe mal nommée
_global.coureur = function(age) {
   this.ageCoureur = age;
} 3. Les conventions de nommage des méthodes ATTENTION N'UTILISEZ JAMAIS D'ACCENTS DANS VOS NOMS DE METHODES ! Les noms de méthodes commencent par des minuscules (en fait, les méthodes ne sont que des variables de type 'Function'). De la même manière, donnez un nom explicite à vos méthodes dans le création de vos classes. Le nom de la méthode doit expliquer ce qu'elle fait. Les conventions de nommage des variables s'appliquent pour les arguments. Utilisez des verbes à l'infinitif pour décrire les actions. Utilisez les verbes 'pouvoir', 'avoir' ou 'être' à la troisième personne du singulier et au présent pour les méthodes retournant des valeurs booléennes :Coureur.prototype.verifierDopage = function() { ... }
Coureur.prototype.peutBoire = function() { ... }
Coureur.prototype.aFaim = function() { ... }
Coureur.prototype.estMajeur = function() { ... } 4. Les conventions de ciblage des variables Cette convention est issue directement de Flash, et ne concerne que rarement d'autres languages. En Flash, essayez de systématiquement cibler vos variables. Il est conseillé de cibler même les variables globales (avec '_global'), ou les propriétés d'un objet (avec 'this'). Le ciblage implicite de Flash peut être bien pratique, mais un programmeur qui va regarder votre code, n'a que le ciblage pour savoir d'où vient votre variable. Il saura alors que les variable ciblées sur 'this' sont des propriétés (ou variables de l'objet en cours), que les variables ciblées sur '_global' sont des variables globales, et que les autre sont des variables locales. Les seuls cas ou le ciblage n'est pas recommandé sont :

• pour les variables locales, déclarées avec var, ou les arguments d'une fonction car de toutes façons, on ne peut pas les cibler facilement.
• pour les classes. Dans la plupart des cas, les classes sont déclarées dans '_global'. En effet, l'opérateur 'new' utilisée permet de repérer facilement le fait qu'il s'agisse d'une classe : ne pas utiliser le _global ne nuit donc pas à la compréhension du code.

N'utilisez que du ciblage relatif, c'est a dire qui part de l'endroit ou vous êtes. Proscrivez dans la mesure du possible les '_level' et '_root'. Utiliser ces deux ciblages revient à se bloquer toute possibilité de ré-utiliser votre code à un autre endroit que celui pour lequel vous l'avez prévu au départ (ce qui fini la plupart du temps par arriver). 5. Les convention d'indentation du code L'indentation est le fait d'introduire des décalages au début des lignes (tabulations). L'éditeur ActionScript de Flash effectue l'identation tout seul, et comporte même un outil qui permet de la faire automatiquement (en partie). Si vous n'utilisez pas cet outil, ou si vous utilisez d'autres éditeurs (comme UltraEdit par exemple), ou plus simplement si vous utilisez Flash5, il existe quelque règles. Les blocs de code entre des accolades '{' et '}' sont décalées d'un cran :Coureur.prototype.recupererCategorie = function() {
   if (this.ageCoureur > 45) {
      return "Vétéran";
   } else {
      return "Senior";
   }
} Certains programmeurs mettent un retour à la ligne avant les accolades d'ouverture '{'. C'est un choix personnel de chacun, car certains trouvent cela plus lisible, d'autres non. :Coureur.prototype.recupererCategorie = function()
{
   if (this.ageCoureur > 45)
   {
      return "Vétéran";
   }
   else
   {
      return "Senior";
   }
} Pour l'instruction particulière 'switch', effectuez aussi un décalage pour les instructions situées aprés un 'case'. Mettez également un seul 'case' par ligne :Course.prototype.peutParticiper = function(coureur) {
   if (coureur.recupererCategorie == "Vétéran") {
      switch(this.difficulte) {
         case "facile" :
         case "normal" :
            return true;
            break;
         case "difficile" :
            return false;
            break;
         default :
            return false;
            break;
      }
   } else {
      return true;
   }
} 6. Les conventions de commentaires Les commentaires sont une des bases les plus importantes pour la compréhension d'un code. Bien qu'un code proprement écrit soit plus facile à comprendre, chaque programmeur garde sa propre logique, qui n'est pas forcément celle des autres. Pour qu'un code soit compréhensible, il faut donc l'expliquer. Pour écrire un commentaire sur une ligne, utilisez le "double slash" ( '//' ) et pour commenter un bloc de texte, encadrez le par '/*' et '*/' :// Ceci est une ligne de commentaire
/* Ceci est un bloc de commentaire
Il peut comporter plusieurs lignes */ En POO, certaines normes existent concernant les classes et méthodes :

• Pour les classes, dans le commentaire précédant la déclaration, spécifiez :
  • Le nom de la classe
  • Ce qu'elle contient, et ce à quoi elle sert
  • Son(ses) auteur(s)
  • Les remarques et spécifités à savoir sur la classe
• Pour les méthodes, vous devez donner :
  • L'action qu'elle effectue
  • Ce qu'elle retourne, et de quelle type est la valeur de retour
  • Chacun de ses paramètres, avec
    • Son type
    • Son nom
    • Sa description
    • S'il est facultatif ou non (si rien n'est spécifié, il est considéré comme obligatoire)

/*****************************
* classe : Course            *
******************************
* Auteur : LAlex             *
*                            *
* Contient une course et     *
* les méthodes pour la gérer *
*                            *
* Attention : ne marche que  *
* pour les courses a pied.   *
******************************/
/*****************************
* Contructeur Course         *
******************************
* Constructeur de la classe  *
* Course                     *
*                            *
* - retour : aucun           *
*                            *
* Paramètres:               *
* - nbKilometres : numerique *
*   longueur de la course    *
*****************************/
_global.Course = function(nbKilometres) {
   this.distance = nbKilometres;
} ATTENTION Le constructeur d'une classe est aussi une méthode, il faut donc le commenter en conséquence ! Evitez de commenter chaque ligne, ou les lignes trop élémentaires. Commentez une action, même si elle comporte plusieurs instructions. Ne faites pas pour autant un roman pour expliquer le 20 prochaines instructions. Un commentaire sur 3 ou 4 instructions qui vont LOGIQUEMENT ensemble est suffisant.Coureur.prototype.verifierVitesse = function() {
   // Si le coureur est trop lent, on l'élimine
   if (this.vitesseMoyenne < 10) {
      this.eliminer();
   // Sinon, si il va trop vite, on fait un test anti-dopage
   // et on l'élimine s'il est positif
   } else if (this.vitesseMoyenne > 60) {
      if (this.verifierDopage()) {
         this.eliminer();
      }
   }
} Le commentaire doit dire ce que ne dit pas le code : parlez de l'action que vous faites, pas des variables que vous manipulez.// Bien commenté
Course.prototype.modifierLongueur = function(longueur) {
   // Modifie la longueur de la course avec la valeur passée en paramètre
   this.longueurCourse += longueur;
}
// (!) Mal commenté
Course.prototype.modifierLongueur = function(longueur) {
   // Rajoute 'longueur' à 'this.longueurCourse' => Sans blagues ?!?
   this.longueurCourse += longueur;
} Aérez un maximum votre code. N'hésitez pas à placer des lignes vides entre des blocs d'instructions différents, même s'il ne comportent pas d'accolades. Par exemple, un retour à la ligne juste avant un commentaire permettra de le différencier du code qui est situé juste avant. 7. Conseils supplémentaires Rassemblez les fonctionnalités analogues au même endroit. Ne déclarez pas une classe à un endroit pour créer ses méthodes à un autre endroit. Utilisez toujours la même langue dans votre code. Si une classe s'appelle 'Coureur', ne faite pas une méthode qui s'appelle 'canRunNaked'... et inversement. Bien entendu, si vous voulez diffuser votre code sur des sites non-francophones, l'anglais reste la meilleure solution! Evitez de mettre plusieurs instuctions séparées par des points-virgules sur une seule ligne. Evitez les écritures condensées :this.ageCoureur > 75 ? trace("Trop Vieux") : trace("OK");
maVariable1 = maVariable2 = maVariable3;
8. Considérations sur le poids des animations

Les conventions précédentes ne prennent pas en considération un problème mineur de Flash, qui est le fait que Flash conserve les noms de variables. Donc un nom de variables long va prendre plus de place (en terme de poids du fichier) qu'un nom de variable d'une ou deux lettres.

La meilleure chose à faire si l'on veut optimiser au maximum est de faire un code avec des noms de variable "conventionnés", puis de le dupliquer et d'utiliser à bon escient le Chercher/Remplacer pour modifier les noms de variables (Attention : une mauvaise utilisation du Chercher/Remplacer peut détruire tout votre code).

9. Conclusion

Comme je vous l'ai précisé au début de ce tutoriel, aucune de ces conventions n'est indispensable au bon fonctionnement de votre code, mais vous constaterez vite, si vous les utilisez, que cela constitue un gain de temps non négligeable, tant pour vous que pour ceux qui voudront lire votre code (par exemple les membres de Flash Forum qui veulent répondre à une de vos question ;))

Annexe A : Les mots réservés

Certains mots utilisés en interne par Flash ne peuvent pas être utilisés comme noms de variables, classes ou méthodes :

• add
• and
  
• break
  
• case
  
• continue
  
• default
  
• delete
  
• do
  
• else
  
• for
  
• function
  
• if
  
• in
  
• instanceof
  
• new
  
• on
  
• return
  
• super
  
• var
  
• void
  
• with

Annexe B : Les mots déconseillés

Certains mots font partie intégrante de la norme ECMA-262 (PDF : ~700Ko), norme dont Flash tend à se rapprocher. Pour une plus grande probabilité de compatibilité avec les versions à venir, il vous est déconseillé d'utiliser les termes suivants pour nommer des variables, classes ou méthodes :

• abstract
  
• boolean
  
• byte
  
• catch
  
• char
  
• class
  
• const
  
• debugger
  
• catch
  
• double
  
• enum
  
• export
  
• extends
  
• final
  
• finally
  
• float
  
• goto
  
• implements
  
• int
  
• interface
  
• long
  
• native
  
• package
  
• private
  
• protected
  
• public
  
• short
  
• static
  
• synchronized
  
• throws
  
• transitient
  
• try
  
• volatile