cancel
Showing results for 
Search instead for 
Did you mean: 

Share your writing guidelines on scripting - Focus on method writing

Highlighted
Community Leader

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; } };

 

 

 

Un sourire et ça repart

Tags (1)
2 REPLIES 2
Highlighted
Community Manager

Re: Share your writing guidelines on scripting - Focus on method writing

Thanks for sharing this, @BenoitB. I've added this great topic to the TechConer area.

Several questions:

  • I don't see any comments inside a function. Do you explain all the actions you do in the code before the function? Sorry, perhaps, it's listed in French, but I don't understand.
  • Have you ever used any code documentation tools? What was your experience?

 

---------
Tanya Gorbunova
SmartBear Community Manager

Did my reply answer your question? Give Kudos or Accept it as a Solution to help others. ⬇️⬇️⬇️
Highlighted
Community Leader

Re: Share your writing guidelines on scripting - Focus on method writing

Hello @TanyaGorbunova 

 

About comments;  yes it's true you should comment when it's NOT trivial only. But as i prepare another post on General guidelines for scripting i've not speak about comments here. It's more on what's your standard way of building a robust and clean function.

 

About documentation tools, i use a nodeJs jsdoc module that i've tweaked, a sample of the result is here:

 

i'll write another post on this subject later, it's planned 😉

 

 

firefox_dHe7rsuB1w.png

 

Un sourire et ça repart

New Here?
Join us and watch the welcome video:
Top Kudoed Authors