JavaScript & Script Coding Best Practice

When using JavaScript within Synergy or CallScripter there are a number of industry best practice principles that can be applied to larger projects.

As principles they may not all apply to every situation and can require judgement in implementation.

Some of these principles are interrelated and should be read in order.

 

 

When an error scenario is reached use a JavaScript exception to flag the issue up to the highest level of JS possible for it to be dealt with. You will see examples of this in the other use cases below.

 

 

Write the logical parts of code so that should any data combination not be valid it is caught and doesn't just fall through. This stops odd results or errors happening when unexpected data is entered.

 

Passing in "true" or "False" would work as expected, but "Bob" or "1" would come back as false. Would this be expected by others if they used the function?

function IsStringTrue (stringToCheck) {
    if(stringToCheck.toLowerCase() == "true") {
      return true;
    }
    else {
        return false;
    }
}

 

 

All code should ideally be stored within a function to allow re-use. Each function should be as precise and short as possible to allow for as much re-use as possible and to keep the functions use simple.

By having smaller precise functions it is also far easier to appreciate, design and handle errors.

 

function DoAgeChecks (age, targetAge, above, minimumAge, maximumAge) {
    if(Number.isInteger(age) &&  Number.isInteger(targetAge)) {
        if(above && age > targetAge) {
            return true;
        }
        else if(!above && age < targetAge) {
            return true;
        }
        else {
            return false;
        }
    }
    else if(Number.isInteger(age) && Number.isInteger(minimumAge) && Number.isInteger(maximumAge) {
        if(age >= minimumAge && age <= maximumAge) {
            return true;
        }
        else {
            return false;
        }
    }
    else {
        throw "DoAgeChecks called without valid parameter options, would be a pain to work out which one is missing";
    }
}

 

function CheckAgeIsOver (age, targetAge) {
    if(Number.isInteger(age) && Number.isInteger(targetAge))
        if(age > targetAge) {
            return true;
        }
        else {
            return false;
        }
    }
    else {
        throw "CheckAgeIsOver called with invalid age or targetAge";
    }
}


function CheckAgeIsUnder (age, targetAge) {
    if(Number.isInteger(age) && Number.isInteger(targetAge)) {
        if(age < targetAge) {
            return true;
        }
        else {
            return false;
        }
    }
    else {
        throw "CheckAgeIsUnder called with invalid age or targetAge";
    }
}

function CheckAgeIsBetween (age, minimumAge, maximumAge) {
    if(Number.isInteger(age) && Number.isInteger(minimumAge) && Number.isInteger(maximumAge)) {
        if(age >= minimumAge && age <= maximumAge) {
            return true;
        }
        else {
            return false;
        }
    }
    else {
        throw "CheckAgeIsBetween called with invalid age or minimumAge or maximumAge";
    }
}

Use Nested Functions

This can be seen in the "Store Code in Precise Functions" example where the built in "Number.IsInteger()" function is called. If nested functions weren't being used I would have had to check the string wasn't blank and that it converted to a number successfully multiple times in my functions.

 

 

By using self descriptive naming in all opportunities the need for separate comments and documentation can be reduced.

A self descriptive name is when a control name, control description or JS function name describes the behaviour and context sufficiently for the calling code to be human readable.

Note: both examples below has descriptive CS variable names (var_xxx) to enhance the examples readability.

 

 

Here it is hard to see what what generally this code section does and what exactly is going to happen when its run. We may have had to open multiple other controls to find this one.

 

Control Name: Set Agent Message text
Control Description: Set agent message from callers name and celebration type
Control Code:

if([var_celebration_type] == "birthday") {
    [var_agent_message] = wrapTextWithExtraText([var_caller_name], "Happy Birthday!";
}
else if([var_celebration_type] == "wedding aniversary") {
    [var_agent_message] = wrapTextWithExtraText([var_caller_name], "Happy Wedding Anniversary!";
}
else if ........

........
........

function wrapTextWithExtraText(middleText, wrappingText) {
    var newText = wrappingText +"   " + middleText + "   " + wrappingText;
    return newText;
}