Adobe Flex Tutorial - Adobe Flex Tutorial

7mar/0912

Flex SDK Coding Conventions et Best Practices

Le Flex SDK étant Open Source, tout le monde peut participer à son développement et proposer son code. Pour éviter que tout le monde code à sa manière avec ses habitudes et sa syntaxe, l'équipe du Flex SDK a publié ses "Coding Conventions and Best Practices" afin que tout le monde ait la même organisation de code, la même indentation etc. Même si vous ne pensez pas contribuer au Flex SDK, ce sont toujours de bon conseils quand vous allez coder en AS3 pour une bonne compréhension du code.

Consulter les conventions de code et Best Practices

Vous trouverez dans ce document, des conseils de syntaxes, d'alignement, d'indentation et de nommage pour ActionScript 3.

Voici quelques exemples:

Déclarations de type

Pour indiquer qu'un tableau contiendra des String, vous pouvez indiquer:

var a:Array /* of String */ = [];

et pas :

var a:Array = [];

Dans une boucle, cela donne donc ceci:

function f(a:Array /* of Number */):Array /* of Object */
{
    ...
}

et pas

function f(a:Array):Array

Opérateur ternaire

Utilisez un opérateur "ternary" au lieu d'un if/else, surtout quand vous testez si une valeur est null:

return item ? item.label : null;

et pas:

if (!item)
    return null;
return item.label;

Boucles for()

Mettez des crochets au corps d'une boucle for, même si elle ne contient qu'une seule instruction:

for (var i:int = 0; i < 3; i++)
{
   doSomething(i);
}

et pas

for (var i:int = 0; i < 3; i++)
    doSomething(i);

Séparez la longeur du tableau dans une variable externe, cela évite qu'elle soit évalué à chaque fois (sauf si vous en avez besoin bien sur)

var n:int = a.length;
for (var i:int = 0; i < n; i++)
{
    ...
}

et pas:

for (var i:int = 0; i < a.length; i++)
{
    ...
}

… et bien d'autres dans ce document:

Consulter les conventions de code et Best Practices

Remplis sous: ActionScript, Flex Builder || Taggé comme: ActionScript, AS3, Best Practices, Coding Conventions Laisser un commentaire

Articles similaires

Commentaires (12) Trackbacks (0) (Souscrire aux commentaires de cet article)

Faridus
9 mars 2009

C'est bien de donner des conventions de nommage mais il vaut mieux privilégier quand même la lisibilité du code.

Pourquoi écrire ça (qui donne mal aux yeux)
var a:Array /* of String */ = [];

plutôt que ça
var stringArray:Array = [];

IL FAUT BIEN NOMMER SES VARIABLES !

conseil de base aux débutants

Surtout, on évite ça qu'on écrit quand on veut embêter son petit camarade de projet
function f(a:Array /* of Number */):Array /* of Object */
{
…
}

C'est une vraie horreur à lire.

Désolé pour le ton du commentaire mais ça m'a hérissé le poil de lire ce genre de choses.

De toute manière on peut trouver de bonnes conventions de codage ici:

http://java.sun.com/docs/codeconv/

Et elles ont bientôt 10 ans…

En tout cas amusez-vous bien avec Flex…
fnicollet
9 mars 2009

J'avoue que cela peut nuire un peu à la lisibilité. Mais par exemple pour le type de retour Array contenant des Object, on ne peut pas indiquer objectArray puisqu'on attend un type. De même, les variables doivent porter un nom cohérent suivant leur utilisation mais pas forcement leur types. Par exemple, on ne vas pas nommer un tableau d'urls urlsStringArray:Array mais plutôt urls:Array /* of String */ = [].
Le reste du code en devient plus lisible

Fabien
Faridus
9 mars 2009

Mouais…

Bon j'ai quelques années de java derrière moi et deux ans de Flex/ActionScript.
Mais il y a un truc qui me chiffonne vraiment c'est le commentaire DANS l'instruction.
Un développeur de mon équipe m'écrit un truc du genre

urls:Array /* of String */ = [].

Il me copie 100 fois à la main :
"Je ne mets pas de commentaire au milieu de l'instruction pour ne pas nuire à la lisibilité du code"
Moins il y a de commentaire dans du code mieux on se porte.
Pour reprendre ton exemple si ton tableau contient des URL, on nommera la variable

var urlArray:Array = [].

1) on sait que c'est un tableau d'URL
2) tout le monde sait qu'une URL c'est une String sinon on utiliserait pour une URLRequest par exemple urlRequestArray:Array.

Au risque d'insister, la lisibilité du code est primordiale.

Farid
fnicollet
9 mars 2009

Bon admettons que je n'ai pas choisi un très bon exemple ^^. Les coding conventions font un peu toujours débat.
Merci en tout cas de donner une perspective venue du monde Java, ça ne fait pas de mal, loin de la

Fabien
Faridus
9 mars 2009

Y'a pas de quoi !

Pour le mxml on a encore du mal à trouver une manière d'écrire le code pour qu'il soit lisible mais en AS, j'ai repris les conventions Java.

Il ne manque plus qu'un bon IDE et on y arrivera… ;^)
fnicollet
9 mars 2009

J'ai vu une vidéo dernièrement sur la prochaine version de Flex Builder, il y aura de bonnes nouveautés comme la génération directe d'ASDoc (l'équivalent de la JavaDoc) qu'il faut se faire à la main pour l'instant ou la génération des getters/setters comme on le fait en Java
Wait and see
popov
27 août 2009

"for (var i:int = 0; i < 3; i++)
{
doSomething(i);
}

et pas

for (var i:int = 0; i < 3; i++)
doSomething(i);"

Pourquoi faire lisible quand on peut pourrir le code d'accolades lol
fnicollet
27 août 2009

Tu verras, le code est bien plus lisible avec des accolades, même s'il est 1 ligne plus long. Essaie de commenter ton doSomething et tu auras des suprises

Fabien
Anonyme
20 janvier 2010

"Moins il y a de commentaire dans du code mieux on se porte."

Oula, je ne suis pas d'accord du tout. Il faut au contraire des commentaires. Par contre, je suis d'accord sur le fait qu'il faut interdire les commentaires au milieu d'une commande.

Au lieu de :

COPIER-COLLER
Actionscript:
urls:Array /* of String */ = [];
Il vaut mieux quelques choses qui s'apparente à ça :

COPIER-COLLER
Actionscript:
urls:Array = []; /* Array of string */
Pareil pour les fonctions où j'aurai tendance à privilégier le formalisme JavaDoc :

COPIER-COLLER
Actionscript:
/** Fonction f qui permet de ...

* @param a Tableau de Number...

* @throws event Génère l'événement...

* @return Tableau d'objet...

*/

function f(a:Array /* of Number */):Array /* of Object */
fnicollet
20 janvier 2010

Je rejoins ton avis sur les commentaires. Pour l'histoire des commentaires au milieu d'une commande, j'ai adopté la première notation car je la trouve plus lisible

Fabien
Anonyme
9 juin 2011

Des commentaires oui mais des commentaires *utiles*

Il n'y a rien de plus inutile que ca :

[as]
/**
* @param a the a to set
*/
public function set setA(a : String) : void {
this.a = a;
}
[as]

C'est malheureusement très courant ...
Faridus
9 juin 2011

Non, non et non !

Appeler une variable "a", juste "a", c'est vraiment n'importe quoi.
Une variable décrit exactement ce qu'elle doit représenter (sinon on ne ferait pas de l'objet).
Le formalisme javadoc doit être utilisé AMHA pour décrire le fonctionnement un peu sioux d'une méthode. On s'en fout des paramètres (surtout dans les getters/setters)

Dans tous les cas c'est une hérésie d'écrire

COPIER-COLLER
Actionscript:
/** Fonction f qui permet de ...

* @param a Tableau de Number...

* @throws event Génère l'événement...

* @return Tableau d'objet...

*/

function f(a:Array /* of Number */):Array /* of Object */
La fonction f, elle a un nom qui comme les variables doit permettre d'indiquer ce qu'elle fait rien qu'en lisant le code
si je suis l'asdoc
* Fonction f qui permet de ....: inutile
* param: a n'importequoi. Je l'appelle arrayOfNumbers
* throws event Génère l'événement: traduction inutile soit c'est un event générique auquel cas on se fout du commentaire, c'est écrit dans le code, soit c'est une sous-classe d'événement dans ce cas le nom de la classe doit servir tout seul
* return tableau d'object on le voit bien que c'est un tableau, pourquoi le redire ?

Bref, la méthode je l'appellerais comme ça (ça s'appelle du code auto documenté cf les bonnes pratices Agiles)

COPIER-COLLER
Actionscript:
function generateObjectArrayFromNumberArray(arrayOfNumbers:Array):Array
Y'a besoin d'autre choses ?

Si son fonctionnement est trop compliqué, on la refactore et sinon on peut mettre un commentaire en asdoc

Bref, les exemples de code au-dessus sont trop commentés.

Désolé