Share your writing guidelines on scripting - Focus on method writing

Hello all,

Please share and discuss about your writing guidelines focused here on your standard way of building a script method.

Below i give you mine, French inside.

This is a standard guideline, not a strict rule, we adapt especially on the result type (not necessary a single boolean but can be a complex return).

Template méthode d’un objet métier :

Règle 101 – En-tête
En-tête documentation de la méthode, respecter la syntaxe suivante permettant une génération automatisée de la documentation.

/**
*  Description
*  @memberof nomObjetMetier
*  @function
*  @param {type paramètre} nom paramètre - description
*  @param {type paramètre} nom paramètre = valeur par défaut- description
*  @param {type paramètre} [nom paramètre optionnel = valeur par défaut] - description
*  @returns {type retour} description
*/

Type paramètre/type retour :
string, number, boolean, Object

Description :
Les balises html peuvent être utilisées pour décorer la documentation générée.
Les retours à la ligne doivent être traitée via l’inclusion balise <br>

Exemple d’en-tête :
/**
*  Appeler un écran Manhattan<br>
*  S'il est déjà ouvert alors bascule dessus<br>
*  Si l'écran est présent (après appel ou bascule) alors currentForm[ScreenCode] est associé à l'écran demandé
*  @memberof mhnEngine
*  @function
*  @param {string} ScreenCode - Code de l'écran à appeler ("Stock article", "Ordres de dis...", "oLPN", "Sites")
*  @param {boolean} [Shortcut = false] - <b>True</b> alors passe par click sur raccourci plutôt que par menu 
*  @returns {boolean} Renvoie <b>true</b> si la fonction s'est exécutée sans erreur<br>
*  Si la fonction a échoué alors la propriété <i>errorString</i> est mise à jour avec la valeur de l'erreur sinon elle est mise à <b>""</b>
*/


Règle 102 – Nommage méthode
Nom de la méthode : Nommage selon la règle Verbe d’action + Objet concerné, en lower camel-case.

Exemple verbe d’action :
call
launch
close
delete
get
set
create
…

Exemple d’objet concerné :
Screen
Menu
Invoice
Budget
Lines
…

Exemple de nom de méthode :
callScreen


Règle 103 – Paramètres méthode
Paramètres de la méthode : Nom court explicite en upper camel-case.
Si possible, affecter une valeur par défaut au paramètre.

Exemple de paramètres de méthode :
(ScreenCode = "101CREATEREPORT", ByShortCut = false)

Règle 104 – Corps méthode
Corps de la méthode :

Etapes à respecter :

 1  – définir les valeurs par défaut des paramètres
 2  – tracer la méthode appelée
 3  – encadrer dans un try .. catch .. finally
 4  – 1ere instruction du try ..  est le contrôle de validité des paramètres obligatoires
 5  – les variables internes de la méthode doivent être déclarées en lower camel-case (pour différencier des paramètres de la méthode qui sont en upper camel-case)
 6  – le catch doit contenir un appel à la gestion générique des erreurs 
 7  – le finally garanti le suivi de retour 
 8  – Dans la mesure du possible ne faire qu’un retour de type boolean.

Exemple :
function callM3Screen (ScreenCode = "SC100", ByShortcut = false) 1   {
  if (system.debug)
    Log.Message("callScreen(" + ScreenCode + ", " + ByShortcut + ") - Appel d'un menu via l'en-tête ou les raccourcis", "", pmLowest); 2     
  try {  3     
    if ((ScreenCode == undefined) || (ScreenCode == ""))   4     
      throw Error("Le paramètre obligatoire ScreenCode est non renseigné !");
    // Petite adaptation pour les ordres de distribution
    let screenCode2  5  = ScreenCode == "Ordres de dis..." ? "Ordres de distribution" : ScreenCode; 
     …
     …
     …
  }
  catch(e) {
    errorString = e.message;  6     
  }
  finally {
    return (errorString == ""); 7   8     
  }
}

And an example of a standard system tools method with these guidelines, a usefule function to stop a process :

/**
 * Arrêter/tuer un processus en mémoire
 * @memberOf system
 * @function
 * @param {string} ProcessName - Nom du processus a arrêter
 * @param {boolean} [SoftKill=false] - <b>true</b> alors essaye d'arrêter le processus de manière normale avec un <i>close/<i> avant de tenter un <i>terminate</i> dessus
 * @param {number} [Trials=10] - Nombre de tentative d'arrêt du processus avant de lever une erreur
 * @returns {boolean} Renvoie <b>true</b> si le processus a été arrêté, <b>false</b> si échec de l'arrêt ou une erreur s'est produite (journalisation)
 */
function killProcess(ProcessName = "", SoftKill = false, Trials = 10) {
  let result = true;
  if (system.debug)
    Log.Message("killProcess(" + ProcessName + ", " + SoftKill + ", " + Trials.toString() + ") - Arrêt de process", "", pmLowest, system.logDebug);
  try {
    if (ProcessName == "")
        throw Error("Le nom du processus n'est pas fourni !");
    let i = 0;
    let p = Sys.FindChild("ProcessName", ProcessName);
    while (p.Exists) {
      i++;
      if (system.debug)
        Log.Message("Tentative d'arrêt n°" + i + " du process " + ProcessName + ", PID = " + p.Id, "", pmLowest, system.logDebug);
      if (SoftKill) {
        p.Close();
        if (!p.WaitProperty("Exists", false))
          p.Terminate();
      }
      else
        p.Terminate();
      if (i > Trials)
        throw Error("Le processus est toujours présent après " + Trials + " tentatives d'arrêt !");
      p = Sys.FindChild("ProcessName", ProcessName);
    }
  }
  catch(e) {
    result = false;
    Log.Message("killProcess(" + ProcessName + ", " + SoftKill + ", " + Trials.toString() + ") - Echec arrêt process : " + e.message, "", pmHighest, system.logError);
  }
  finally {
    return result;
  }
};