NOTE: MY POSTINGS REFLECT MY OWN VIEWS AND DO NOT NECESSARILY REPRESENT THE VIEWS OF MY EMPLOYER, ACCENTURE.
DIFFICULTY LEVEL: BEGINNER
Assumes a good beginner level of knowledge and/or familiarity with Scripting in ServiceNow.
One of the biggest issues I see when supporting code is the lack of code formatting in custom scripts. This can be potentially a serious issue, and I have seen it lead to some bad mistakes! Here I will cover some of what I consider best practices in coding format. I will present the good, the bad, and the ugly! 🙂
Indentation
Indentation allows a coder to quickly see variable relationships, variable scoping, function placement, open and closed brackets placement, and … well you get the idea. It vastly improves readability. Again, don't be of the OLD school: If it hard to write it ought to be hard to read! This simply does NOT work and is not a software engineering best practice!
Personally, I like code to be indented, where appropriate, by 3 to 4 spaces (or a tab covering that amount). The editor format button is your friend!
Example 1: Badly indented code.
And before you ask, yes, I have seen this type of stuff in the ServiceNow platform code, but mostly with custom code!
var results = getResults();
function getResults() {
var incidents = new GlideRecord('incidents');
incidents.query();
while(incidents.next()){
gs.print(incident.number+'');
if (incident.number=='INC0000012')
break;
if(incident.number=='INC0000012')
gs.print('hello world');
}
}
Example 2: Ugly
And see things like this as well!
var results = getResults();
function getResults() {
var incidents = new GlideRecord('incidents');
incidents.query();
while(incidents.next()){
gs.print(incident.number+'');
if (incident.number=='INC0000012')
break;
if(incident.number=='INC0000012')
gs.print('hello world');
}}}
Example 3: Properly indented code
The following is much better! Remember: White space is cheap. Use it a lot, use it wisely!
var results = getResults();
function getResults() {
var incidents = new GlideRecord('incidents');
incidents.query();
while (incidents.next()){
gs.print(incident.number+'');
// brackets even around one line improve readability
// AND allow for easier insertion of debugging statements.
if (incident.number=='INC0000012') {
break;
}
if (incident.number=='INC0000012') {
gs.print('hello world');
}
}
}
Formatted you can actually see the hierarchy of the code! Readability for maintenance!
Formatting
Example 1: Badly formatted code
Really the bad and the ugly are the same here.
var incidents=new GlideRecord('incidents'),mainCount=0;incidents.query();
if(incidents.next()){gs.log(incident.number+'';}
Example 2: Good
This is a marked improvement.
var mainCount = 0;
var incidents = new GlideRecord('incidents')
incidents.query();
if (incidents.next()) {
gs.log(incident.number+'';
}
White Space
Whitespace is good. Don't worry about adding an extra line here or there, or putting spaces where it makes sense for readability:
Example 1: Bad
if(myHat=='green'){}
for(var i=0;i<checkList.length;i++){}
gs.print('incident number:'+incident.number+','+incident.short_description+'.');
while(incidentRecords.next()){}
Example 2: Good
if (myHat == 'green') {
}
for (var i=0; i < checkList.length; i++) {
}
gs.print('incident number:' + incident.number + ',' + incident.short_description + '.');
while (incidentRecords.next()) {
}
Again: space is cheap. Readability is all!
The Script Editor
Just a couple of side-notes on the out-of-the-box (OOtB) editor. It isn't too bad for formatting. It has a couple of gotchas which I will explain, and throws formatter warnings on stuff that is not necessarily important.
NOTE: The formatter button is hard coded OOtB to indent exactly 4 characters (it inserts a 4-character tab). There is no property to change this.
Editor Quirk 1: Comments Can Cause Bad Formatting - Fixed. The editor behaves now.
In some cases the format button gets confused when code is commented out. Any following code is indented incorrectly.
Editor Quirk 2: Switch statement causes bad formatting - Fixed. The editor behaves now.
It aligned all of internal code inside of the switch! Fix: Don't click the format button if you have a "switch" statement in your code. With this sort of thing I format it in my external editor (Notepad++, or Sublime work fine) and copy-and-paste my code into the script editor.
Editor Quirk 3: Spaces vs. Tabs - Fixed. The editor behaves now.
In some cases your editor will throw a warning about mixed spaces and tabs. Ignore these. They are not important (unless you are obsessive about such things).
Handles it fine now with now warning message:
Conclusion
So in summary: Formatting is a best practice in code development. Always keep in mind that you are probably not the only one that will be maintaining your code. Don't leave a mess. Good formatting habits are worth cultivating, and making a personal standard (as well as a corporate standard). Use the editor format button as much as possible. Keep in mind it has a couple of quirks!
Enjoy!
Steven Bell.
If you find this article helps you, don't forget to log in and mark it as "Helpful"!
Originally published on: 10-29-2015 11:27 AM
I updated the code and brought the article into alignment with my new formatting standard.
4 Comments
