Forums Développement Multimédia

Les formations Mediabox
Les formations Mediabox

Ecrire correctement en ActionScript

Compatible ActionScript 3. Cliquer pour en savoir plus sur les compatibilités.Compatible ActionScript 2. Cliquer pour en savoir plus sur les compatibilités.

Traduction hasardeuse réalisé par [ NikO ] de l'excellent article de Simon Wacker : http://www.simonwacker.com/blog/archives/000087.php

Les développeurs travaillant en équipe doivent/devraient écrire leurs codes de la même manière.

Cela permet à d'autres de relire et modifier facilement le code d'autrui. Pour cela il est nécessaire d'avoir des normes et conventions d'écriture commune sur lesquelles se référer.

Cette convention d'écriture a été réalisé durant le dévellopement de As2Lib FrameWork. Je veux remercier Alex Uhlmann et Martin Heidegge pour leurs relectures et leurs conseils concernant ce document.

Documentation des méthodes

/**
 * Returns an array that contains the methods represented by {@link MethodInfo}
 * instances, this type and super types' declare, that are not filtered/excluded.
 *
 * <p>The {@link TypeMemberFilter#filter} method is invoked for every
 * method to determine whether it shall be contained in the result. The
 * passed-in argument is of type {@code MethodInfo}.
 *
 * <p>If the passed-in method filter is {@code null} or {@code undefined}
 * the result of an invocation of the {@link #getMethodsByFlag} method
 * with argument {@code false} will be returned.
 *
 * <p>{@code null} will be returned if:
 * <ul>
 *   <li>The {@link #getType} method returns {@code null} or {@code undefined}.</li>
 *   <li>
 *     The {@link #getMethodsByFlag} method returns {@code null} or {@code undefined}.
 *   </li>
 * </ul>
 *
 * @param methodFilter the filter that filters unwanted methods out
 * @return an array containing the declared methods that are not filtered,
 * an empty array if no methods are declared or all were filtered or null
 * @see #getMethodsByFlag
 */
public function getMethodsByFilter(methodFilter:TypeMemberFilter):Array {
    if (!getType()) return null;
    if (!methodFilter) return getMethodsByFlag(false);
    var result:Array = getMethodsByFlag(methodFilter.filterSuperTypes());
    for (var i:Number = 0; i < result.length; i++) {
        if (methodFilter.filter(result[i])) {
            result.splice(i, 1);
            i--;
        }
    }
    return result;
}

Obligations

  • La documentation d'une méthode commence toujours pas le délimiteur /** et se termine par */.
  • Chacun de ces délimiteurs doit se trouver sur une ligne seule.
  • Toutes les lignes intermediaires doivent contenir le caractère * avec un espace blanc juste aprés.
  • La longueur d'une ligne ne devrait pas dépasser 80 caractères, en prenant en compte l'indentation et le caractere *.

La documentation d'une méthode est composée d'une description générale, suivi de tags spécifiques, exemples :

Bon exemple

/**
 * [Main Description]
 *
 * [Tag Section]
 */

Mauvais exemple

/** [Main Description]
 * [Tag Section]
 */

ou :

/**
 *
 *[Main Description]
 
* [Tag Section]
*/

Positionement et alignement

La documentation d'une méthode précéde sa déclaration et est indentée de manière à s'aligner avec, il ne doit y a voir aucune ligne vide entre la fin de la documentation et le début de la déclaration.

Bon exemple

/**
 * ..
 */
public function getName(Void):String;

Mauvais exemple

/**
 * ..
 */
 
    public function getName(Void):String;

Conjugaison

Cela est un peu plus subjectif, mais c'est tout de même important à souligner. Utiliser la troisieme personne du singulier, plutôt que la seconde personne.

Bon exemple

/**
* Renvoie un tableau qui ..
*/

Mauvais exemple

/**
 * Renvoies un tableau qui ..
*/

Lorsque vous vous référez à une occurence/instance de la classe, dites le clairement.

Bon exemple

/**
 * Renvoie un tableau des logs de l'occurence/instance
*/

Mauvais exemple

/**
 * Renvoie un tableau des logs de cette classe
*/

Ecrivez cela clairement, plutôt que d'utiliser raccourci et langage sms …

La description générale

La description générale commence à la ligne suivant le délimiteur \**. Le 1er paragraphe est un petit résumé concis, mais complet.

Suit un résumé complet, avec une ligne vide, et des paragraphes formaté html <p> bla bla</p> qui donnent des informations plus détaillées sur la méthode, avec une ligne vide entre chaque paragraphe html.

Documentez les cas spéciaux, par exemple, si tel parametre est défini à null ou si une méthode dépendante renvoie null. Essayez d'être le plus complet possible, pour que les dévellopeurs puissent utiliser intégralement cette méthode en lisant uniquement sa documentation.

Vous devriez néanmoins essayer d'écrire la description dans son implémentation indépendante au possible, et spécifier les problémes liés aux dépéndances uniquement lorsque nécessaire car la documentation définie un contract avec la méthode et toute surcharge de méthode (over-writing) ou implémentation particuliere. Cela signifie que plus la description est précise et complete, plus il sera difficile de modifier/réécrire la méthode sans violer les principes de sa description.

Bon exemple

/**
 * Courte description.
 *
 * <p>Paragraphe 1 qui est séparé par un {@code <p>} html. Il peut 
 * être écrit sur plusieurs lignes et contenir plusieurs phrases. Limit the line length
 * Limitez la taille des lignes à 80 characteres.
 *
 * <p>Paragraphe 2 est aussi séparé par un {@code <p>} html.
 *
 * <p>{@code null} est renvoyé si :
 * <ul>
 *   <li>Case one.</li>
 *   <li>Case two.</li>
 *   <li>Case three.</li>
 * </ul>
 *
 * [Tag Section]
 */

Mauvais exemple

/**
 * Longue description sur ce que la méthode fait. Elle n'est pas courte, et ne fait que décrire tout sans reélle structure.
 * De plus la ligne fait plus de 80 characteres.
 * <p>Il n'y a pas de ligne vide avant le <p>. Cela rendera la lecture de la documentation
 * plus difficile. Les codes en-ligne ne sont pas entouré de {@code}. Les cas spéciaux ne sont pas listés. 
 * [Tag Section]
 */

La section tag

La section tag est séparée de la description générale par une ligne vide. Elle commence toujours par un @ qui constitue le début d'un bloc tag. Cette section décrits les arguments/paramètres @param, ce que la fonction renvoie @return et les erreurs générées @throws par les méthodes. Il y a aussi les @see pour renvoyer vers d'autres portions de codes, comme des méthodes liées.

Bon exemple

/**
 * [Main Description]
 *
 * @param parameterUn le premier parametre qui ..
 * @param parameterDeux le second parametre qui ..
 * @return renvoie ..
 * @throws valeur illégale si {@code parameterUn} est {@code null}
 * @see #doSomethingSimilar
 * @see org.as2lib.env.reflect.ClassInfo#forInstance
 */
public function doSomething(parameterUn:String, parameterDeux:Number):String;

Mauvais exemple

/**
 * [Main Description]
 *
 * @param parameterDeux le second parametre qui ..
 * @return renvoie ..
 * @see org.as2lib.env.reflect.ClassInfo#forInstance
 */
public function doSomething(parameterOne:String, parameterDeux:Number):String;

Ordre des tags

Ajoutez les tags dans l'ordre suivant :

@param parameter-name description
@return description
@throws class-name description
@see package.class#member label
@see <a href="url#value">label</a>
@see ''string''
@deprecated deprecated-text

@param parameter-name description :
les tags @param sont rangés dans le même ordre que leurs déclaration dans la méthode. description est une phrase incomplete qui décrit le paramètre. Elle commence par une phrase en bas de casse et ne contient pas de . pour la terminer. Il est possible d'utiliser plusieurs ligne. Si un paramètre est optionnel rajoutez (optional) aprés le nom du paramètre et avant sa description.

Exemple :

@param [parameter-name] (optional) [description]

Si la méthode accepte un nombre inconnu de paramètre, signalez le dans la documentation avec le tag @param et .. comme nom de paramètre. Ajoutez une description pour tout ses autres paramètres. Si les paramètres doivent être d'un type spécifique, dites le dans la description.

Exemple :

@param .. [description]

@return description:
Ajoutez @return pour toutes les méthodes qui ne retournent pas Void et qui ne sont pas des constructeurs. description est une phrase partielle qui décrit le type du retour et ses valeurs possibles. Elle commence par une phrase bas de casse. Il est possible d'employer plusieurs lignes. Déclarez les retours de cas spéciaux, comme null par exemple.

@throws class-name description:
class-name est le nom de l'erreur générée par la méthode. description est une phrase partielle qui donne les cas générateurs d'erreurs. Elle commence par une phrase bas de casse. Il est possible d'employer plusieurs lignes. Ce tag est tres important et ne doit pas être omis car sinon, il est impossible de savoir pourquoi des erreurs sont générées et dans quels cas elles sont générées sans devoir chercher dans l'ensemble de la méthode les throws qui sont en cause ou qui générent des erreurs à l'execution.

Exemple :

@throws UnknownOverloadHandlerException si aucun écouteur overload n'a été trouvé

@see reference:
Jetez un oeil au tag @see dans la documentation java, ainsi que sur la manière de ranger plusieurs tags @see.

Tags en ligne :
Comme dit précédement, les descriptions générales et pour la section tags peuvent contenir des tags. Ils apparaissent avec des {@tag}. Ils peuvent être utilisés partout où le texte est autorisé. Les plus courants sont {@link} pour renvoyez vers une page spécifique et {@code} pour faire resortir une portion de code.

Exemple :

La méthode {@link TypeMemberFilter#filter} est invoquée ..

ou :

Si l'argument passé est {@code null} ou ..

Si vous renvoyez vers ou faites resortir une méthode en omettant ses (), cela rendera la lecture plus facile et plus naturelle.

Bon exemple :

La méthode {@link TypeMemberFilter#filter} est executée ..

Mauvais exemple :

La méthode {@link TypeMemberFilter#filter(MethodFilter):Boolean} est executée ..

{@link package.type#member label} :
Cela insère un lien visible qui pointe vers un package ou une classe spécifique de la documentation. Le tag label est optionel. Si vous ne le spécifiez pas le nom de la classe sera utilisé. Ne rajoutez pas de liens vers toutes les classes dans votre documentation. Les liens attirent l'attention du lecteur, cela peut rendre la documentation plus difficile à lire si il y a profusion de liens. Liez une seule fois la classe dans la description de la méthode. Vous pouvez aussi juste mettre en avant les classes en utilisant le tag {@code} dans la description générale et rajouter un @see dans la section tag ensuite.

Exemple :

La méthode {@link #getMethodsByFlag} renvoie ..

{@code text}: Affiche le texte avec la police dédiée aux codes. Utilisez {@code} pour faire resortir les noms de méthodes, classes, packages, interfaces, propriétés, variables ou null et undefined.

Exemple :

{@code null} est renvoyé si ..

<code>text</code>:
Affiche le texte avec la police dédiée aux codes. Utilisez ce code html si votre code est sur plusieurs lignes et que vous désirez le garder ainsi, si il n'est pas inclus dans une phrase.Le tag ouvert <code> est suivi par </code>. N'utilisez pas d'indentation avec des tabulations, mais remplacez les par 4 espaces blanc. Le tag </code> est placé sur une ligne seule et est aligné sur son tag d'ouverture correspondant, il signifie la fin de cette portion de code.

Exemple ( impossible à faire avec la syntaxe du wiki … ):

// debut balise < code >
  var server:LocalServer = new LocalServer("local.as2lib.org");
  server.putService("myServiceOne", new MyServiceOne());
  server.putService("myServiceTwo", new MyServiceTwo());
  server.run();
// fin balise </ code >

ou :

// debut balise < code >
  var client:LocalClientServiceProxy = new LocalClientServiceProxy("local.as2lib.org/myService");
  var callback:MethodInvocationCallback = client.invoke("myMethod", ["p1", "p2"]);
  callback.onReturn = function(returnInfo:MethodInvocationReturnInfo):Void {
      trace("myMethod - return value: " + returnInfo.getReturnValue());
  }
  callback.onError = function(errorInfo:MethodInvocationErrorInfo):Void {
      trace("myMethod - error: " + errorInfo.getException());
  }
// fin balise </ code >

Déclaration des méthodes

Les méthodes sont déclarées dans les classes et interfaces. La méthode déclarée est la partie se trouvant avant les {} suivants. Elle est constituée de son accés public ou private, le paramètre optionnel static, ensuite function, le nom de la méthode, la liste des paramètres dans les () et séparés par des , et finalement, le typage de ce qu'elle renvoie. Les interfaces déclarent les méthodes tandis que les classes les implémentent.

Exemple d'une méthode déclarée et implémentée dans une classe :

public static function getLogger(loggerName:String):Logger {
    // Implementation omitted
}

Exemple d'une méthode déclarée dans une interface :

public function isDebugEnabled(Void):Boolean;

Longueur de ligne :
La longueur de ligne de la déclaration d'une méthod, comme partout ailleurs dans le code, ne devrait pas dépasser 120 caractères. Un retour ligne devrait être fait entre 80 et 120 caractères, lorsque la longueur de maximale est dépassée. Cela permet d'imprimer le code, et de l'afficher dans n'importe quel éditeur. La ligne aprés un retour ligne doit être indentée de 8 caratères blanc pour la séparer visuellement du corps de la méthode. Comme vous pouvez le constater il est difficile d'avoir une déclaration de méthode qui dépasse la longueur maximale d'une ligne. Si vous avez une méthode déclarée de cette manière, vous avez peut-être mal fait quelque chose …

public static function doSomethingVeryVeryVeryInteresting(argumentOne:ReallyInterestingClass, argumentTwo:ArgumentTwo,
        argumentThree:String, argumentFour:Number):String {

Visibilité et accés aux méthodes

Publique :
public est l'accés le plus courant. Les méthodes publiques sont accéssible de n'importe où dans votre application.

Privée :
private est l'accés le plus restrictif. Un membre privé n'est accéssible que par sa classe ou une de ses sous-classes.

Usage :
Cachez les méthodes aussi souvent que possible. Moins de méthodes sont publiques, plus lisible, plus facile à tester, à modifier est la classe. Une méthode déclarée publique dévrait toujours être une méthode demandée par une interface et implémentée par la classe, pour sa configuration, comme des setters/getters. Déclarez toujours la visibilité d'une méthode, même si elle par défaut elle est publique en ActionScript 2. Le problème étant que les dévelloppeurs qui lisent le code ne savent pas forcement que par défaut une méthode est publique, cela rend le code plus difficile à lire.

Bon exemple :

public function getLevel(Void):LogLevel;

Mauvais exemple :

function getLevel(Void):LogLevel;

Portée des méthodes

Par occurence/instance :
C'est le cas par défaut. Vous n'avez pas à déclarer les méthodes à être utilisée par instance avec un mot spécial. Cela signifie que vous invoquez une méthode d'une occurence d'une classe et non pas une méthode de classe. Ainsi vous devez d'abord instancier la classe, avant de pouvoir invoquer une de ces méthodes. Utilisez ce type de fonctionnement aussi souvent que possible et oubliez les méthodes de classe. Les méthodes par instance sont plus flexibles et vous ouvrent les portes des Designs Patterns et de la Programmation Orientée Objet (POO - OOP en anglais) comme le polymorphisme. Vous pouvez utiliser this pour vous référer à la l'occurence de la classe créée à l'interieur de la méthode invoquée.

public function doSomething(Void):Void {
    trace(„The method ‚doSomething’ is invoked on instance: “ + this);
}

Par classe (static):
Aussi connu comme méthodes statiques. Vous devez les déclarer en utilisant static. Ce mot est placé aprés la déclaration de la visibilité de la classe, et avant function. Les méthodes de classes sont disponibles par classe et non pas instance de classe. Cela signifie que vous invoquez directement la méthode sur la classe. Il est impossible de les invoquer via les occurences de classe. Vous y accédez en utilisant le nom de la classe puis le nom de la méthode : MaClass.maMethode(). Les méthodes statiques déclarées dans les classes peuvent être invoquées par d'autres méthodes de classe, statique ou non, simplement en donnant leur nom, inutile de spécifier la classe. Utilisez les méthode statiques uniquement si elles sont réélement appropriées, car il y a de rééls problème liés à leur utilisation :

  • Les méthodes statiques ne peuvent être déclarées dans les interfaces.
  • Tout les appels doivent se faire à partir de la classe elle-même, impossible d'appeler à partir d'une occurence de celle-ci.
  • Les méthodes statiques ne peuvent être surchargées.
  • Les méthodes statiques ne peuvent modifier que les propriétés de classe. Cela signifie que toutes les occurences de la classe auront ces propriétés modifiées, partout dans votre application.

Comme vous pouvez le voir, utiliser les méthodes statiques rend votre code moins flexible et plus sujet aux erreurs, lorsque qu'une méthode statique modifie les propriétés des occurences de d'une classe. Une utilisation utile est appropriée d'une méthode statique est par exemple org.as2lib.env.log.LogManager.getLogger(loggerName:String):Logger. Cette méthode est utilisée pour retourner les loggers d'une classe, et elle est utilisée par toutes les classes de l'application qui en ont besoin. Elle n'ajoute pas vraiment de fonctionnalités, mais renvoie juste tout les informations nécessaires vers la classe qui est utilisée pour lancer l'application. Il n'est pas possible d'utiliser le mot cléfs this directement dans une méthode statique, cela provoque une erreur à la compilation. Si néanmoins vous désiriez faire cela, vous pouvez utiliser eval ainsi eval(“th”+“is”).

Exemple :

public static function doSomething(Void):Void {
    trace("La méthode statique ‚'doSomething' est invoquée sur la classe : " + eval("th" + "is"));
}

Nommage des méthodes

Le nom d'une méthode commence par un texte. Ce texte décrit au mieux ce que la méthode réalise. Il est possible d'ajouter d'autres mots pour expliquer d'avantage celle-ci. Jetez un oeil à la section setter/getter pour plus d'informations concernant les préfixes communément utilisés.

Bon exemple :

public function loadXmlData(xmlDataSource:String):Void;

Mauvais exemple :

public function xmlData(xmlDataSource:String):Void;

Majuscule et miniscule :
La 1ère lettre d'une méthode est écrit en minuscule. Les mots cléfs suivants ont leur premiere lettre en majuscule. Lorsque que vous utilisez des abbréviations comme XML dans le nom de la méthode, ne mettez que la 1ère lettre en majusucule. Si l'abbréviation ne contient que deux lettres, ne les mettez pas en majuscule. Par exemple, n'utilisez pas MC pour les MovieClips dans les noms de méthodes.

Bon exemple :

public function loadXmlData(xmlDataSource:String):Void;

ou :

public function createMovieClipLoader(Void):MovieClipLoader;

Mauvais exemple :

public function loadXMLData(xMLDataSource:String):Void;

ou :

public function createMcLoader(Void):MovieClipLoader;

Suffixes :
N'utilisez pas des suffixes qui se référence aux parametres tel que to, than et by dans les noms de méthodes.

Bon exemple :

public function isMoreExplicit(overloadHandler:OverloadHandler):Boolean;

ou :

public function apply(object);

ou :

public function move(x:Number, y:Number):Void;

Mauvais exemple :

public function isMoreExplicitThan(overloadHandler:OverloadHandler):Boolean;

ou :

public function applyTo(object);

ou :

public function moveBy(x:Number, y:Number):Void;

Pluriel et singulier :
Les noms des méthodes peuvent être au pluriel. Cela peut signifier que la méthode renvoie la collection d'un certains nombres d'élements dans le nom est spécifié dans la déclaration de la méthode. Je ne suis pas l'avocat de l'utilisation de l'utilisation du type de collection dans les noms de méthodes. Le type est déja déclaré avec le retour return dans l'implémentation de la méthode et ne devrait donc pas se retrouver à nouveau dans le nom de celle-ci.

Bon exemple :

public function getAllListeners(Void):Array;

Mauvais exemple :

public function getAllListenerArray(Void):Array;

ou :

public function getListenerArray(Void):Array;

ou :

public function getAllListener(Void):Array;

La langue : Ecrivez les noms de méthodes en Anglais US pour être sur que tout les dévelloppeurs pourront lire clairement les noms de méthodes. Utiliser des mots anglais est aussi garant que tout les lettres de l'alphabet nécessaire sont utilisables pour les noms de méthodes.

Actuellement : Le nom d'une méthode devrait suffir à expliquer celle-ci. Pour se diriger vers ce but, n'utilisez pas les abbréviations. Utilisez uniquement si elles sont communes et que vous êtes réélement sûr que les dévelloppeurs sauront ce qu'elles signifient. N'oubliez pas de documenter vos abbrevations dans la documentation liée à votre code. Vous devriez donc clairement écrire les noms des méthodes avec le maximun d'informations nécessaire pour les rendre claires et sans ambiguités.

Prenons un exemple, une classe BeanDefinition. Cette classe est responsable des informations concernant beans. Ainsi on a le nom de bean et la définition de la classe de bean. Vous pourriez nommez les deux getters getName et getClass, mais quelqu'un pourrait mal les interpréter et penser que getName renvoie le nom de la classe, pareil pour getClass. Mais en utilisant getBeanName et getBeanClass, il devient trés difficile de se tromper dans l'interpretation, les quelques caractères supplémentaires à écrire ne sont pas choquants. Cela signifie, sans généraliser, qu'il est important de bien signifier l'action d'une méthode dans son nom.

Le nom d'une méthode devrait suffir en lui-même : loadXmlData, ce nom suffit à expliquer que quelque chose est chargé en dehors de flash, que cela est de l'information, et que cette information est sous forme XML. Cela signifie aussi que le chargement peut échouer et donc qu'il peut être nécessaire de porter une attention particuliere aux erreurs, aux retours null ou à des événements onError

Bon exemple :

public function loadXmlData(xmlDataSource:String):XmlLoaderCallback;

Mauvais exemple :

public function load(source:String):XmlLoaderCallback;

Paramètres des méthodes

Les parametres sont déclarés après le nom de la méthode, séparé par des virgules. La liste commence par ( et se termine par ). le ( est placé juste après le nom de la méthode, sans espace blanc entre les deux. Avant chaque nouveau paramètre il faut une virgule et un espace blanc. Chaque paramètre doit avoir un nom et être typé. Le typage est réalisé en utilisant le typage for ActionScript 2 ainsi : myParametre:MyType et non pas myParametre : MyType.

Bon exemple :

public function log(message:String, level:LogLevel):Void;

Mauvais exemple :

public function log ( message,level ):Void;

ou:

public function log(message : String,level : LogLevel) : Void;

Le nom du parametre doit être explicit et suffisant. Il devrait aussi expliquer l'utilisation de celui-ci.

Bon exemple :

public function loadXmlData(xmlDataSource:String):Void;

Mauvais exemple :

public function loadXmlData(source:String):Void;

Vous pourriez utiliser le prefix new pour les parametres des setters :

public function setName(newName:String):Void;

Comme avec le nom de la méthode, le nom du parametre devrait être écrit en Anglais US pour s'assurer de la compréhension de la méthode par n'importe quel dévellopeur.

A l'utilisation :
Dut à la nature molle et à quelques bugs de ActionScript 2 concernant les paramètres, nous devons faire attention sur la manière dont nous les utilisons. Normalement, une méthode doit déclarer tout ses paramètres et leurs types.

Exemple :

/**
 * [Main Description]
 *
 * @param level the level to check whether this logger is enabled for it
 * @return true if this logger is enabled for the passed-in {@code level}
 * else false
 */
public function isEnabled(level:LogLevel):Boolean;

Mais, si un paramètres n'est pas typé, n'utilisez pas Object pour le typer, laisser le paramètre seul. Faites ainsi car le compiler Macromedia pense que les instances de classe ne sont pas du type Object lorsque la méthode est implémentée par rapport à une interface. Dans ce cas, vous pourriez juste faire une interface de marquage, qui ne déclare aucune méthode, mais ne fait que signer la classe :

/**
 * [Main Description]
 *
 * @param target the target object to stringify
 * @return the string representation of the passed-in {@code target}
 * object
 */
public function stringify(target):String;

Si la méthode ne prend aucun paramètre, ne laisser pas simplement vide la liste des paramètres, cela pourrait signifier que la méthode peut prendre en compte un nombre inconnu de paramètre, préferez spécifier Void comme paramètre.

/**
 * [Main Description]
 *
 * @return the name of this bean 
 */
public function getBeanName(Void):String;

Si ma méthode accepte un nombre inconnu de paramètres, includant aucun paramètre, laisse vide la liste des paramètres. Par exemple, cela est utile dans le cas de surcharge de méthode, qui transfert les fonctionnalitées à d'autres méthodes en fonction des paramètres passés.

Exemple normal :

 
/**
 * [Main Description]
 *
 * @param .. any number of values, that are of the expected type that was
 * specified on construction, to concat with this array
 * @return an array that contains the values of this array as well as the
 * passed-in ones
 */
public function concat():TypedArray;

Exemple de méthode surchargée :

/**
 * @overload getBeanByName
 * @overload getBeanByNameAndType
 */
public function getBean();
 
/**
 * [Main Description]
 * 
 * @param beanName the name of the bean to return
 * @return the bean corresponding to the passed-in {@code beanName}
 */
public function getBeanByName(beanName:String);
 
/**
 * [Main Description]
 *
 * @param beanName the name of the bean to return
 * @param beanType the expected type of the bean to return
 * @return the bean corresponding to the passed-in {@code beanName} that
 * is of the expected {@code beanType}
 */
public function getBeanByNameAndType(beanName:String, beanType:Function);

Si la méthode peut utiliser un nombre indéfini de paramètres, mais que au moins un est déclaré dans la documentation, alors déclarez aussi son type si il est connu.

Exemple :

/**
 * [Main Description]
 *
 * @param neededParameter [description]
 * @param .. any number of parameters that are of type {@code String}
 * and [further description]
 */
public function doSomething(neededParameter:String):Void;

et :

/**
 * [Main Description]
 *
 * @param value the new value, that is of the expected type specified on
 * construction, to add to the end of this array
 * @param .. any number of values, that are of the expected type specified
 * on construction, to add to the end of this array
 * @return the new length of this array
 */
public function push(value):Number;

N'oubliez pas de commenter tout les cas spéciaux, de façon claire, comme dans les exemples ci-dessus.

Typage des renvois

Décrivez toujours le typage du return d'une méthode. Si la méthode ne renvoie rien, déclarez Void tout de même.

/**
 * [Main Description]
 *
 * @return the name of this bean
 */
public function getBeanName(Void):String;
 
/**
 * [Main Description]
 *
 * @param beanName the new name of this bean
 */
public function setBeanName(beanName:String):Void;

Si le type du retour ne peut être spécifié, n'utilisez pas Object comme type, mais laisser le typage du return vide. Faites ainsi car le compiler Macromedia considère que les instances de classe qui implémentent des interfaces ne sont pas de type Object :

/**
 * [Main Description]
 *
 * @return the message object to log
 */
public function getMessage(Void);

Implémentation des méthodes

La méthode est implémentée à l'interieur des {}. Le { est sur la même ligne que la déclaration de la méthode et est séparé de celle-ci par un espace blanc. La première ligne de code est à la ligne suivante, tabulée avec 4 espaces blancs. Le } est sur la dernière ligne, seul et est aligné avec la déclaration de la méthode.

Bon exemple :

public function getBeanName(Void):String {
    return beanName;
}

Mauvais exemple :

public function getBeanName(Void):String{
return beanName;
}

ou :

public function getBeanName(Void):String {
    return beanName;
    }

ou :

public function getBeanName(Void):String
{
    return beanName;
}

Récupération des erreurs :
Chaque méthode devrait implémentée ses propres systèmes de récupération d'erreur. Cela signifie qu'il doit être possible d'executer n'importe quelle méthode, public ou private dés que des cas spéciaux tel que null en paramètre, sauf, si cette méthode est ensuite surchargée par une sous classe. Ne déléguez pas la gestion des erreurs à d'autres méthodes.

super :
Dans le corps de la méthode, vous pouez utilisez l'operateur super qui implicitement invoquera la méthode de la super classe. Même si il est possible d'invoquer super à chaque fois vers les méthodes des super classes, utilisez le uniquement si vous surchargez une méthode, et que vous désirez invoquer la méthode surchargée.

Longueur de ligne :
Comme lors de la déclaration de la méthode, la longueur d'une ligne ne devrait pas dépasser 120 caractères. Si votre code dépasse la longueur maximale, faites un retour à la ligne entre 80 et 120 caractères. Cela rend possible l'impression du code, et le rend lisible dans la plupart des éditeurs. Le code mis à la ligne est indenté de 8 espaces blancs, pour séparer celui-ci du corps de la méthode.

Exemple :

throw new IllegalArgumentException("The types of the arguments [" + arguments + "] must match one of the two choices.",
        this, arguments);

Les renvois des méthodes

Une méthode peut repondre à une execution en renvoyant une valeur. Cette valeur peut être par exemple, le résultat d'un calcul ou peut informer l'executeur du succés ou non de l'execution. Dans les Designs Patterns bas niveau, vous pouvez renvoyez des valeurs. Dans les bons Designs Patterns, il est plutôt recommendé d'utiliser les exceptions car elles renvoient plus d'informations, tel que ce qui est faux, et à quel moment cela est arrivé. Pour qu'une méthode renvoie une valeur utilisez return, cette déclaration doit être suivi d'un espace blanc, puis de la valeur à renvoyer. Si la valeur est le résulat d'un calcul, mettez le entre (). N'utilisez pas de parenthèse, si vous renvoyez une instance en utilisant l'operateur new.

Bon exemple :

return size;

ou :

return (size != null ? size : defaultSize);

ou :

return new MyClass();

Mauvais exemple :

return (size);

ou:

return size != null ? size : defaultSize;

ou:

return (new MyClass());

ou :

return(size != null ? size : defaultSize);

Exceptions:

Il faut générer une exception pour indiquer que quelque chose s'est mal déroulé. Il est nécéssaire de faire la distinction entre les exceptions dites normales et les exceptions fatales. Les exeptions normales sont classiquement interceptées et gérées par l'application, alors que les exceptions fatales indiquent une erreur de programmation qui doit être gérée dans le code du developpeur. Les exceptions fatales sont par exemple : org.as2lib.env.except.IllegalArgumentException qui lance une exception lorsqu'un un argument illégal est rencontré, ainsi que org.as2lib.env.except.AbstractOperationException lancée lorsque le développeur oublie de surcharger une méthode abstraite.

Une exception normale est org.as2lib.io.conn.core.client.UnknownServiceException qui est lancée si le service distant n'est pas disponible actuellement. L'application peut attraper cette exception et par exemple lancer une nouvelle tentative de connexion après avoir attendu une seconde. Les exceptions sont lancées à partir de la commande “throw”. Il ne faut pas mettre de parenthèses après le mot clé “throw”.